Steps for submitting first FPS to GoogleChrome/first-party-sets repository

[Ralph Brown]

I will confess, I am relatively new to GitHub and am probably making some newbie mistakes, but I did want to validate that I understand the process correctly. I would appreciate any comments or corrections to the sequence of steps necessary to submit the first FPS for a domain.

1. Create a GitHub account
2. Sign the Google Contributor License Agreement (CLA) https://cla.developers.google.com/
3. Create the first_party_sets.json file for the <domain> of interest
4. Place this file under "https://<domain>/.well-known" (this being necessary prior to a pull request)
   
5. Fork the GoogleChrome/first-party-sets repository
6. Edit first_party_sets.JSON file in the forked repository, replacing the current contents of this file with just the contents of the first_party_sets.json for the <domain> of interest
7. Create a pull request for the forked repository requesting a merge to the main branch
8. The workflow will perform the necessary checks and report the success of the pull request or not

I am a little fuzzy on how the step 6, editing the first_party_sets.JSON file in the forked repository. I am assuming that the contents should just be the first_party_sets.json for the <domain> of interest, because that is what is being checked. However, that seems to imply that the pull request is asking to replace the complete list of first party sets with just the first_party_sets.json for the <domain> of interest. Alternatively, step 6 would be to simply add the contents of the first_party_sets.json for the <domain> of interest at the beginning of the first_party_sets.JSON file in the forked repository, but then this does not match the file at "https://<domain>/.well-known/first_party_sets.json".

Thanks for any assistance.

Ralph

[Ralph Brown]

I reviewed the FpsCheck.py code and I think I may have answered my own question on step 6. It isn't as I originally suggested in step 6, rather it is "add the contents of the first_party_sets.json for the <domain> of interest at the beginning of the first_party_sets.JSON file in the forked repository." This of course makes sense, because at a later date you may want to update the FPS for the domain of interest. In which case, you would go to the relevant FPS in the first_party_sets.JSON file in the forked repository and modify it appropriately, leaving the rest of content in place.

Let me know if I don't have this right.

Thanks,

Ralph

[Chris Fredrickson]

HI Ralph,

Your second email is correct: the expectation is for first_party_sets.JSON to contain the entire list of First-Party Sets. So, each pull request would simply modify that list as needed, depending on whether some set(s) needs to be added, removed, or modified.

In practice, I think it'd be nice if our tooling ensured that the list of sets was sorted by primary domain (e.g.), but I'm not sure if we've implemented that yet. Once we've done that, you would add your new set in the corresponding position in the list, rather than at the beginning of the list.

Additionally, you're correct that the automated checks we've written are currently executed against the entire list. We'd like to enhance the tooling such that only the changes being introduced in the PR are checked, but we haven't done so yet.

Chris

[Ralph Brown]

Chris,

Thanks for confirming my understanding.

However, I would not recommend that the list of sets be sorted (except perhaps in the back-end for consumption by the browser if that is of benefit).

One would expect that this list of FPS to grow to be fairly large. To keep it as simple as possible, I would recommend the submission guidelines ask that a new FPS be prepended to the top of the list. I think asking the submitter to scroll through a lengthy list to find the appropriate insertion point is burdensome and probably subject to human error.

With respect to updates to an existing FPS in the list, someone who is updating an existing FPS in the list will know the primary domain of interest and can easily search for that entry and modify it in place appropriately. Sorting the list isn't necessarily going to make it significantly easier for the submitter in this case.

Ralph

[Chris Fredrickson]

On Monday, May 1, 2023 at 10:21:13 AM UTC-4 ra...@brownwolfconsulting.com wrote:

Chris,

Thanks for confirming my understanding.

However, I would not recommend that the list of sets be sorted (except perhaps in the back-end for consumption by the browser if that is of benefit).

One would expect that this list of FPS to grow to be fairly large. To keep it as simple as possible, I would recommend the submission guidelines ask that a new FPS be prepended to the top of the list. I think asking the submitter to scroll through a lengthy list to find the appropriate insertion point is burdensome and probably subject to human error.

I think tooling can address the possibility of human error. Either a "linter" that just checks that the sets are in the correct order (similar to the current automated checks), or a formatter which automatically reorders them (ideal, but slightly more work on our part).

 

With respect to updates to an existing FPS in the list, someone who is updating an existing FPS in the list will know the primary domain of interest and can easily search for that entry and modify it in place appropriately. Sorting the list isn't necessarily going to make it significantly easier for the submitter in this case.

Actually, I think keeping the list sorted does make it significantly easier for the submitters. If all submitters are told to prepend to the start of the list, then the risk of merge conflicts from concurrent PRs is very high (actually ~100%), and will require a lot of re-syncing/rebasing busy-work on the part of anyone submitting a PR. In contrast, if the list is kept sorted, then independent PRs will not cause problems for each other unless they happen to involve alphabetically-adjacent primary domains (which I expect to be rare).

I also think that keeping the list sorted makes it easier for people to find their sets once the list becomes large (without forcing them to resort to Ctrl-F), and doesn't preclude the use of Ctrl-F. So I personally would still prefer to keep the list sorted.

[Ralph Brown]

Chris,

Excellent points and it makes sense. I hadn't considered the issue of merge conflicts, which of course gets to be a problem.

It might be helpful to add language to the Submission Guidelines that spells some of this out. I am happy to submit a pull request. As a new comer to this, I can bring a set of fresh eyes.

Ralph