|
| 1 | +--- |
| 2 | +pcx_content_type: how-to |
| 3 | +title: Content reviews |
| 4 | +meta: |
| 5 | + title: Content reviews | How we docs |
| 6 | +--- |
| 7 | + |
| 8 | +import { GitHubCode } from "~/components"; |
| 9 | + |
| 10 | +We work (and appreciate working) in [GitHub](https://github.com/cloudflare/cloudflare-docs), but it's not a perfect tool by any means. |
| 11 | + |
| 12 | +We've added several ergonomic improvements to help us triage incoming work, streamline reviews, and automate communication. |
| 13 | + |
| 14 | +## Triage work |
| 15 | + |
| 16 | +To help our writers triage work (and help with backend reporting), we automate a few labels and issue / pull request assignment. |
| 17 | + |
| 18 | +### Pull requests |
| 19 | + |
| 20 | +For pull requests, we use a specific [GitHub action](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/pr-label-assign.yml) to add labels and assign codeowners. |
| 21 | + |
| 22 | +- [Label products](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/actions/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. |
| 23 | +- [Label size](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/actions/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: |
| 24 | + |
| 25 | + <GitHubCode |
| 26 | + repo="cloudflare/cloudflare-docs" |
| 27 | + file=".github/actions/label-size/index.ts" |
| 28 | + commit="3dd03fdad79b2663631a6530794dfd1ad15bdc03" |
| 29 | + lines="20-36" |
| 30 | + lang="ts" |
| 31 | + code={{ title: "label-size.ts" }} |
| 32 | + /> |
| 33 | + |
| 34 | +- [Assign codeowners](https://github.com/cloudflare/cloudflare-docs/tree/production/.github/actions/assign-pr): We use our [CODEOWNERS](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/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. |
| 35 | + |
| 36 | +### Issues |
| 37 | + |
| 38 | +For issues, we use a similar [GitHub action](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/issue-label-assign.yml) to add labels and assign codeowners. |
| 39 | + |
| 40 | +Our [script](https://github.com/cloudflare/cloudflare-docs/tree/production/.github/actions/issue-label-assign) 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. |
| 41 | + |
| 42 | + |
| 43 | +## Streamline reviews |
| 44 | + |
| 45 | +To streamline reviews, we use several automations to help solve common reviewer issues. |
| 46 | + |
| 47 | +### Will this break anything? |
| 48 | + |
| 49 | +We have one required check that runs on every commit, [CI](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/ci.yml). |
| 50 | + |
| 51 | +This check makes sure that: |
| 52 | + |
| 53 | +- The site builds correctly. |
| 54 | +- All [internal links](/style-guide/how-we-docs/links/#internal-links) are valid. |
| 55 | +- There are no [infinite redirects](/style-guide/how-we-docs/redirects/#infinite-redirects). |
| 56 | +- Specific pages and functionality in our docs [behave as expected](https://github.com/cloudflare/cloudflare-docs/blob/production/worker/index.worker.test.ts). |
| 57 | + |
| 58 | +### Who needs to approve this? |
| 59 | + |
| 60 | +We commonly get questions about approvals, especially for pull requests that touch multiple product areas (or our components). |
| 61 | + |
| 62 | +We have a specific part of [CI](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/ci.yml#L32) that [posts a comment](https://github.com/cloudflare/cloudflare-docs/blob/production/bin/post-codeowners-comment/index.ts) with the relevant codeowners. |
| 63 | + |
| 64 | + |
| 65 | + |
| 66 | +### What changed? |
| 67 | + |
| 68 | +We use a [GitHub action](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/publish-preview.yml) to publish preview builds for every commit on a pull request (and [comment those links](https://github.com/cloudflare/cloudflare-docs/tree/production/bin/post-preview-url-comment) 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). |
| 69 | + |
| 70 | +We are in the process of migrating to [Workers Builds](/workers/ci-cd/builds/git-integration/github-integration/), which provides that functionality natively. |
| 71 | + |
| 72 | +Based on feedback, we have also added a before/after table of links to help reviewers easily find links in the preview builds. |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | +### Is there anything else I need to check? |
| 77 | + |
| 78 | +Two difficult things to check are potential redirects and changes to [content snippets (partials)](/style-guide/components/render/) that are used on multiple pages. |
| 79 | + |
| 80 | +We have a [specific action](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/potential-redirects-or-partials.yml) that posts a comment to help reviewers identify and then check these attributes. |
| 81 | + |
| 82 | + |
| 83 | + |
| 84 | +The partials part of the comment specifically [links to the usage for that partial](/style-guide/components/render/?partial=1.1.1.1/all-ipv4), which helps writers know the various pages where it appears. |
| 85 | + |
| 86 | +## Automate communication |
| 87 | + |
| 88 | +We automate communication primarily through the [`no-response`](https://github.com/lee-dohm/no-response) GitHub Action. |
| 89 | + |
| 90 | +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. |
| 91 | + |
| 92 | +The ones without enough context, however, are often painful (especially in a [busy repo](https://github.com/cloudflare/cloudflare-docs/pulse) 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. |
| 93 | + |
| 94 | +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](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/no-response.yml) 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](https://github.com/cloudflare/cloudflare-docs/issues/22943#issuecomment-3002211164). |
| 95 | + |
| 96 | + |
| 97 | + |
| 98 | +This workflow - we hope - balances the needs our of team with a healthy respect for our contributors. |
| 99 | + |
| 100 | +### Stale issues |
| 101 | + |
| 102 | +We intentionally avoid the [`stale` workflow](https://github.com/github/docs/blob/main/.github/workflows/stale.yml) that closes pull requests or issues that have been inactive for a specific period of time. |
| 103 | + |
| 104 | +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. |
0 commit comments