Skip to content
Cloudflare Docs

Content reviews

We work (and appreciate working) in GitHub ↗, but it's not a perfect tool by any means.

We've added several ergonomic improvements to help us triage incoming work, streamline reviews, and automate communication.

Triage work

To help our writers triage work (and help with backend reporting), we automate a few labels and issue / pull request assignment.

Pull requests

For pull requests, we use a specific GitHub action ↗ to add labels and assign codeowners.

  • Label products ↗: We add labels for the top-level product folder, which helps writers scan incoming pull requests and see which are relevant to them.

  • Label size ↗: We add labels for the size of the pull request, which helps writers see the relative size of the difference. It's not a perfect measure, but we use the lines changed to estimate the size of the pull request:

    label-size.ts
        switch (true) {
          case changes <= 10:
            label = "size/xs";
            break;
          case changes <= 100:
            label = "size/s";
            break;
          case changes <= 500:
            label = "size/m";
            break;
          case changes <= 1000:
            label = "size/l";
            break;
          default:
            label = "size/xl";
            break;
        }

  • Assign codeowners ↗: We use our CODEOWNERS ↗ file to automatically assign people to pull requests based on the files changed. This assignment helps writers scan and filter to see which pull requests are relevant to them.

Issues

For issues, we use a similar GitHub action ↗ to add labels and assign codeowners.

Our script ↗ treats issues because usually they contain links to our site instead of files within the repository. We grab the associated links in the issue description fields and then use those to assign writers (again based on CODEOWNERS) and add product labels.

Streamline reviews

To streamline reviews, we use several automations to help solve common reviewer issues.

Will this break anything?

We have one required check that runs on every commit, CI ↗.

This check makes sure that:

Who needs to approve this?

We commonly get questions about approvals, especially for pull requests that touch multiple product areas (or our components).

We have a specific part of CI ↗ that posts a comment ↗ with the relevant codeowners.

Codeowners comment

What changed?

We use a GitHub action ↗ to publish preview builds for every commit on a pull request (and comment those links ↗ on the pull request). This action ensures that reviewers can see exactly what the site and content will look like when they're rendered (and not just look at the changed markdown in GitHub).

We are in the process of migrating to Workers Builds, which provides that functionality natively.

Based on feedback, we have also added a before/after table of links to help reviewers easily find links in the preview builds.

Before/after table

Is there anything else I need to check?

Two difficult things to check are potential redirects and changes to content snippets (partials) that are used on multiple pages.

We have a specific action ↗ that posts a comment to help reviewers identify and then check these attributes.

Potential redirects or partials comment

The partials part of the comment specifically links to the usage for that partial, which helps writers know the various pages where it appears.

Automate communication

We automate communication primarily through the no-response ↗ GitHub Action.

Being open source means that we accept issues and pull requests from anyone! And a lot of these are either self explanatory or have enough context for us to follow up on them.

The ones without enough context, however, are often painful (especially in a busy repo ↗ like ours). A writer has to ask for more detail, then remember to check back in, and then sometimes re-ask for more detail, and then check in again.

To help avoid some of this mental toil, we'll ask a question and then apply the more-information-needed label. This label starts a 14-day clock ↗ for the author to respond. If they do respond, the label gets removed and the conversation can continue. If they don't respond, the issue automatically gets closed with a comment explaining why ↗.

No response comment

This workflow - we hope - balances the needs our of team with a healthy respect for our contributors.

Stale issues

We intentionally avoid the stale workflow ↗ that closes pull requests or issues that have been inactive for a specific period of time.

In our opinion, this workflow causes more friction and frustration than it solves. Just because something has been around for a year doesn't mean it's not still relevant.