Issues from the google/fonts
repository are used to define the Google Fonts production pipeline for team members, and for users to report bugs or suggest new submission ideas.
Since google/fonts
only hosts binaries, and since we want these files to be in sync with the ones in the upstream repositories, onboarders manage the sources and builds from the upstream repo. This link between what happens upstream and what is reported downstream is made through the issues.
Example: https://github.com/google/fonts/issues/3730
The issues should follow these rules:
One issue per font family.
Onboarders can also use the issues as a progress tracker of their assigned projects by adding a checklist in the first comment and regular notes.
They have labels.
At least a primary category label (start with I
). Further information about labels below.
E.g I Font bug.
There should be a new issue for any new project commissioned
And that even before delivery from the designer. These should have the label commissioned and should be into a milestone. A non-commisioned project’s issue is assigned to a milestone if we plan to take care of it.
Issues in milestones should be assigned to an onboarder.
Sometimes they are not assigned for a while, but any issue planned for this quarter or the next should have an onboarder assigned and also added in their project board. Otherwise no one will take care of it.
The original authors of the font should be tagged in the related issue.
The issue become then the place for the designer update us about their progress and notify onboarders that the font is ready for review. If they have a problem, they can also report it there and link to the specific issue; this way we have a good track of the different events that stop us from onboarding a font.
An issue should be linked to the PR that fixes it.
This allows automatic closing of the issue when the linked PR is merged.
An issue must contain a link to a font’s upstream repo
Sometimes, multiple sources of a font can exist on GitHub, or a source may be difficult to find. To make life easy for onboarders, a link to the source repo must be included.
Milestones are used to have an overview of the upcoming year, and to divide the workload into reasonable charges.
They are divided into quarters.
They should contain every issue about commissioned projects,
Same for non-commissioned projects (accepted) that we intend to onboard that quarter.
Important projects to be commissioned and milestoned is the milestones for issues posted by users that we consider worth taking care of.
They should be placed into a Quarter milestone when commissioned or assigned.
We assess the milestones at the end of each quarter
We close them when the due date is passed. The issues that were not completed before the end of the milestones get moved to the next milestone.
Issues in milestones should be assigned to an onboarder
They should be placed into their respective project board.
Milestones are for issues only; there are no PRs in milestones.
To make a change to the google/fonts
repo, onboarders submit a Pull Request which is then reviewed by a team member. According to the result of this review, the PR is merged or not.
Example: https://github.com/google/fonts/pull/4320
PRs should follow these rules:
Each should be linked to the issue it fixes.
They should be added to Traffic Jam if the changes they bring should be carried out to the API.
They should have labels.
At least 2: a status label (start with -
) and a category label (start with I
). More info about the labels in the section below.
E.g - Ready for review I New font.
The issue is closed when the linked PR is merged.
If the PR has been properly linked to an issue, then this action is automated. This can cause confusion in the sense that the users will think that when the issue is closed, then the issue is fixed. But the fix carried out by the PR only gets mirrored on the API after validation in the sandbox server and push to production (cf Pull Request Review below). Therefore a few weeks can pass in between. This system is not ideal, but it saves us from manually closing multiple issues when the changes are live.
If the PR gets “blocked” after merging, the issue should be manually reopened and fixed with another PR.
A reviewer should be assigned if the PR needs to be reviewed by someone in particular.
Otherwise no need to do it, and the current reviewer will do it if your PR is Ready for review.
If the PR was made by a user or non-contributor to the repo, it could be assigned to a team member to take care of it.
Most of the time, a team member will have to re-do it because of credentials activating the CI, and general workflow and requirements that are often not respected by non-usual contributors.
PRs and issues are monitored in separate Github project boards.
Each onboarder contracted by GF has a personal project board
They manage their own workload / issue list.
There are only issues in an onboarder’s board.
Since PR and issues are linked, it is then easy for an onboarder to check the status of their PR. So no need to add PRs in one’s personal project board.
PRs are added to the Traffic Jam project.
There are only PRs in this project board, as it is meant to monitor the status of the PR’s content from submission to publication, knowing that its content is supposed to be pushed to 3 different servers: the developer sandbox, the sandbox, and finally the production Google Font API.
Always add labels to items you want to track.
The combination of labels and project boards allow us to track progress, write the push lists, and build stats using different scripts. Therefore the labels and Traffic Jam board should not change name without also changing the gftools gen-push-lists script.
The labels are extremely important in this workflow. They help communication between users, reviewers and onboarders. Scripts and issue templates are also linked to specific label names to generate reports and statistics, and so names should not change without updating the scripts.
I
Primary: Issue and PR [grey]
New font Font upgrade Designer profile Description/Metadata/OFL Font bug Request Axis Registry API/Website/Platform Tools/workflow/repo Knowledge
II
Secondary:
prioritisation for new fonts [light green]: Commissioned Accepted Submission
primary script [dark green]: CJK Indic Arabic Icon → you can create new label if the script is not there
III
Additional: to specify the type of upgrade [light orange]
Expand glyphset Expand styles Improve rendering Small Fix VF Replacement
Status labels are having meaningful colours:
Labels also have meaningful prefixes:
-
Submissions: (Issues and PRs)
Ready for review, In progress, Upstream is working on it.
—-
Result of review: (Issues and PRs)
Usually for font bugs
Bad rendering Glyphset Issues Needs design work Requires axis registration
Usually after reviewing repo/PR:
Needs Meta/Desc/License changes Needs upstream resolution Regression Missing sources Has RFN
Needs more info:
Needs confirmation Needs Dave’s opinion
—– Servers status: (Only merged PRs)
Lists:
to sandbox to production
Servers:
In sandbox Live
Problem after merging:
Blocked API Tofu
The google/fonts repo is linked to a dev-sandbox. A few hours after a change to the repo (once a PR gets merged for example), this change is reflected on that server.
→ These servers act like steps in a pipeline: the change must be uploaded into the dev-sandbox
before it can be be pushed in the sandbox
. Similarly, a change can’t be pushed to production
(live server) if it hasn’t been pushed to sandbox
first.
Once a week, the lists of changes to push to sandbox
and to production
are generated with the script gftools gen-push-lists: it updates the to_sandbox.txt and to_production.txt files that instruct the engineers team which changes they should push to the different servers.
→ When the changes are added to these lists, we can move the PRs into the corresponding columns (In Sandbox list
, In Production list
).
→ The script uses the labels to categorise correctly the changes in the list files.
When the changes are pushed, they get reviewed again. If validated in sandbox
, they can be pushed to production
.
→ The status label can be changed to to production.
→ The push to sandbox and production are staggered biweekly, so each week should happen at least on push to one of the server
→ When the changes are pushed to production, the label can be changed to Live
Add My New Font
A team member inspects the font files and sees good potential. They add the label Need's Dave opinion to check with Dave Crossland (Program manager) if the font is worth being onboarded.
Dave is thrilled, he loves the font and wants it in the library. He removes the label Need's Dave opinion and adds the label Accepted. He adds the issue to a convenient milestone, and during a quarterly meeting where milestones are assessed, he will assign the issue to an onboarder and it gets added to their project board.
The onboarder starts to work on the project upstream. They add the label In progress. While doing QA on the font, they notice some design issues that need to be addressed by the designer. They add the label Needs upstream resolution to the issue to notify that this project is on hold until the issues are resolved by the designer.
The designer makes the requested changes and notifies the onboarder by commenting on the issue. Et cetera.
google/fonts
by making a Pull Request.
Traffic Jam
project.Then, the PR gets reviewed by a team member. The status label is updated according to the result of that review. This time, the reviewer spotted a regression in the spacing, and needs to know if it is a mistake or an improvement. They post an image of the issue and add the label Needs confirmation.
The onboarder checks with the designer, who decides that the regression is a mistake. They change the PR label to Needs upstream resolution.
Once the mistake is fixed, the onboarder updates the PR with the newly build fonts, and changes the status label to Ready for review. Now we go back to the same process as before, but this time the reviewer approves the PR and merge it.
When the PR gets merged, it goes automatically in the the column Just merged / in transit
of the Traffic Jam
project. A few hours later, the new font will appear in the dev-sandbox
, and if it looks good, the label to sandbox
can be added to signify that this font can be pushed to sandbox.
The onboarder’s job is done. The font still needs to get through the servers validation process described above, and if everything goes smoothly, the font should be live on Google Fonts after few weeks.