googlefonts.github.io

Onboarder workflow guide

🐝 Google Fonts has become too big to be maintained as a simple community repository. The platform is now an API distributing and serving more than a thousand fonts families, and GF has started to see itself as a proper open-source foundry. This means several things:
  1. While in the past spontaneous contributions were still possible, today the specifics of the requirements and the security in place have made it complicated for a random user to make such a contribution. As an example, the continuous integration (CI) can only get triggered if a pull request (PR) has been made by someone with permission to the repo. If a user makes a PR, it will definitely draw some attention, but the PR often needs to be re-done by a team member. So while contribution to the repo is not in theory exclusive to the “onboarders” (paid contractors), it tends to be in practice.
  2. GF has commissioned hundreds of fonts from professional type designers. To onboard these projects (from the moment the font family is “ready”), GF needs a toolchain that automates most of the repetitive tasks such as packaging the fonts (gftools packager) and generating QA proofs (gftools qa).
  3. The workflow must leave no place to doubt about the status of the project. Indeed, once merged into the google/fonts repo, the font actually still travels through different servers before appearing on the API. It has often happened that fonts have never got into production — because they have been forgotten in the sandbox server or somewhere else.
This workflow described below was designed so that GF do not lose products during the validation process, to facilitate the validation process, and to keep people updated about the status of different projects. It requires active maintenance and regular updates from team members.

It seemed also important to keep the whole status of the repository in one place, mostly to avoid copy-pasting PR links all the time. GF, therefore, chose a complete Github-based workflow, making extensive use of the issue tracker, the milestones feature, the project boards, and the continuous integration system.

This guide will help team members to understand the validation process of a font family and the actions required from them to help that process.

google.github.io/fonts is a page updated weekly that reports on activity in the google/fonts repo.
Background reading:
nerd  google/fonts repository explained
nerd  Making a PR to Google Fonts

Table of contents

Issue tracker

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

Screenshot of an issue from google/fonts issue tracker.

The issues should follow these rules:

Milestones

Milestones are used to have an overview of the upcoming year, and to divide the workload into reasonable charges.

Screenshot of a quarter Milestone.

Pull Requests

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

Screenshot of a Pull Request from google/fonts PR tab.

PRs should follow these rules:

Project boards

PRs and issues are monitored in separate Github project boards.

Labels

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.

Category

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:

III Additional: to specify the type of upgrade [light orange]

Expand glyphset Expand styles Improve rendering Small Fix VF Replacement

Status

Status labels are having meaningful colours:

Labels also have meaningful prefixes:

The servers validation process

  1. 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.

  2. 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.

  3. 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

Example of workflow

  1. An issue is opened by a user to request the addition of a new font family: “My New Font”. The font is ready to be onboarded upstream, and the user has complied with all the requirements.
    • Title: Add My New Font
    • labels: New font, Submission
  2. 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.

  3. 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.

  4. 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.

  5. The designer makes the requested changes and notifies the onboarder by commenting on the issue. Et cetera.

  6. When the font is built and the QA is good, the onboarder ships the font to google/fonts by making a Pull Request.
    • They add the PR into the Traffic Jam project.
    • They add at least 2 labels to the PR: a category (new, upgrade, designer…) and a status (in progress, ready for review…).
  7. 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.

  8. The onboarder checks with the designer, who decides that the regression is a mistake. They change the PR label to Needs upstream resolution.

  9. 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.

  10. 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.

  11. In parallel of that process the onboarder should have prepared a tweet to officially communicate the font’s arrival on Google Fonts.

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.