Patch

.devcontainer/devcontainer.json

@@ -33,4 +33,5 @@
 
 	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
 	"remoteUser": "node"
+
 }

.dockerignore

@@ -0,0 +1,12 @@
+.devcontainer/
+.git/
+.github/
+.vscode/
+contributing/
+docs/
+node_modules/
+script/
+tests/
+lib/rest/static/dereferenced
+# Folder is cloned during the preview + prod workflows, the assets are merged into other locations for use before the build
+docs-early-access/

.eslintrc.js

@@ -13,7 +13,7 @@ module.exports = {
     babelOptions: { configFile: './.babelrc' },
     sourceType: 'module',
   },
-  ignorePatterns: ['tmp/*'],
+  ignorePatterns: ['tmp/*', '!/.*', '/.next/'],
   rules: {
     'import/no-extraneous-dependencies': ['error', { packageDir: '.' }],
   },

.github/CODEOWNERS

@@ -10,15 +10,19 @@
 /.github/ @github/docs-engineering
 /script/ @github/docs-engineering
 /includes/ @github/docs-engineering
+/lib/search/popular-pages.json @github/docs-engineering
 app.json @github/docs-engineering
 Dockerfile @github/docs-engineering
 package-lock.json @github/docs-engineering
 package.json @github/docs-engineering
 
 # Localization
+/.github/actions-scripts/create-translation-batch-pr.js @github/docs-localization
+/.github/workflows/create-translation-batch-pr.yml @github/docs-localization
 /.github/workflows/crowdin.yml @github/docs-localization
 /crowdin*.yml @github/docs-engineering @github/docs-localization
-/translations/ @github/docs-engineering @github/docs-localization @github-actions
+/translations/ @github/docs-engineering @github/docs-localization @Octomerger
+/translations/log/ @github/docs-localization @Octomerger
 
 # Site Policy
 /content/github/site-policy/ @github/site-policy-admins

.github/actions-scripts/compress-large-files.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import path from 'path'
+import fs from 'fs'
+import zlib from 'zlib'
+import walk from 'walk-sync'
+
+const DRY_RUN = Boolean(JSON.parse(process.env.DRY_RUN || 'false'))
+// Roughly 100KiB means about 25 files at the moment.
+// Set this too low and the overheads will be more than the disk and
+// network I/O that this intends to serve.
+const MIN_GZIP_SIZE = Number(process.env.MIN_GZIP_SIZE || 1024 * 100)
+
+const BROTLI_OPTIONS = {
+  params: {
+    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+    [zlib.constants.BROTLI_PARAM_QUALITY]: 6,
+  },
+}
+main()
+
+async function main() {
+  compressFromPattern('lib/**/static/**/*.json')
+}
+
+async function compressFromPattern(pattern) {
+  const glob = pattern.includes('*') ? pattern.split(path.sep).slice(1).join(path.sep) : undefined
+  const walkOptions = {
+    globs: glob ? [glob] : undefined,
+    directories: false,
+    includeBasePath: true,
+  }
+  const root = path.resolve(pattern.includes('*') ? pattern.split(path.sep)[0] : pattern)
+  const filePaths = walk(root, walkOptions).filter((filePath) => {
+    return fs.statSync(filePath).size > MIN_GZIP_SIZE
+  })
+
+  if (!DRY_RUN) {
+    console.time(`Compress ${filePaths.length} files`)
+    const compressed = await Promise.all(filePaths.map(compressFile))
+    console.timeEnd(`Compress ${filePaths.length} files`)
+
+    console.time(`Delete ${compressed.length} files`)
+    compressed.forEach((filePath) => fs.unlinkSync(filePath))
+    console.timeEnd(`Delete ${compressed.length} files`)
+  }
+}
+
+function compressFile(filePath) {
+  return new Promise((resolve, reject) => {
+    const contentStream = fs.createReadStream(filePath)
+    const newFilePath = `${filePath}.br`
+    const writeStream = fs.createWriteStream(newFilePath)
+    const compressor = zlib.createBrotliCompress(BROTLI_OPTIONS)
+    contentStream
+      .pipe(compressor)
+      .pipe(writeStream)
+      .on('finish', (err) => {
+        if (err) return reject(err)
+        resolve(filePath)
+      })
+  })
+}

.github/actions-scripts/content-changes-table-comment.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import createStagingAppName from '../../script/deployment/create-staging-app-name.js'
+import * as github from '@actions/github'
+import { setOutput } from '@actions/core'
+
+const context = github.context
+
+const githubToken = process.env.GITHUB_TOKEN
+if (!githubToken) {
+  throw new Error(`GITHUB_TOKEN environment variable not set`)
+}
+
+const stagingPrefix = createStagingAppName({
+  repo: context.payload.repository.name,
+  pullNumber: context.payload.number,
+  branch: context.payload.pull_request.head.ref,
+})
+
+const octokit = github.getOctokit(githubToken)
+
+const response = await octokit.rest.repos.compareCommits({
+  owner: context.repo.owner,
+  repo: context.payload.repository.name,
+  base: context.payload.pull_request.base.sha,
+  head: context.payload.pull_request.head.sha,
+})
+
+const { files } = response.data
+
+let markdownTable =
+  '| **Source** | **Staging** | **Production** | **What Changed** |\n|:----------- |:----------- |:----------- |:----------- |\n'
+
+const pathPrefix = 'content/'
+const articleFiles = files.filter(
+  ({ filename }) => filename.startsWith(pathPrefix) && !filename.endsWith('/index.md')
+)
+for (const file of articleFiles) {
+  const sourceUrl = file.blob_url
+  const fileName = file.filename.slice(pathPrefix.length)
+  const fileUrl = fileName.slice(0, fileName.lastIndexOf('.'))
+  const stagingLink = `https://${stagingPrefix}.herokuapp.com/${fileUrl}`
+  const productionLink = `https://docs.github.com/${fileUrl}`
+  let markdownLine = ''
+
+  if (file.status === 'modified') {
+    markdownLine = `| [content/${fileName}](${sourceUrl}) | [Modified](${stagingLink}) | [Original](${productionLink}) | |\n`
+  } else if (file.status === 'added') {
+    markdownLine = `| New file: [content/${fileName}](${sourceUrl}) | [Modified](${stagingLink}) | | |\n`
+  }
+  markdownTable += markdownLine
+}
+
+setOutput('changesTable', markdownTable)

.github/actions-scripts/create-translation-batch-pr.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import github from '@actions/github'
+
+const OPTIONS = Object.fromEntries(
+  ['BASE', 'BODY_FILE', 'GITHUB_TOKEN', 'HEAD', 'LANGUAGE', 'TITLE', 'GITHUB_REPOSITORY'].map(
+    (envVarName) => {
+      const envVarValue = process.env[envVarName]
+      if (!envVarValue) {
+        throw new Error(`You must supply a ${envVarName} environment variable`)
+      }
+      return [envVarName, envVarValue]
+    }
+  )
+)
+
+if (!process.env.GITHUB_REPOSITORY) {
+  throw new Error('GITHUB_REPOSITORY environment variable not set')
+}
+
+const RETRY_STATUSES = [
+  422, // Retry the operation if the PR already exists
+  502, // Retry the operation if the API responds with a `502 Bad Gateway` error.
+]
+const RETRY_ATTEMPTS = 3
+const {
+  // One of the default environment variables provided by Actions.
+  GITHUB_REPOSITORY,
+
+  // These are passed in from the step in the workflow file.
+  TITLE,
+  BASE,
+  HEAD,
+  LANGUAGE,
+  BODY_FILE,
+  GITHUB_TOKEN,
+} = OPTIONS
+const [OWNER, REPO] = GITHUB_REPOSITORY.split('/')
+
+const octokit = github.getOctokit(GITHUB_TOKEN)
+
+/**
+ * @param {object} config Configuration options for finding the PR.
+ * @returns {Promise<number | undefined>} The PR number.
+ */
+async function findPullRequestNumber(config) {
+  // Get a list of PRs and see if one already exists.
+  const { data: listOfPullRequests } = await octokit.rest.pulls.list({
+    owner: config.owner,
+    repo: config.repo,
+    head: `${config.owner}:${config.head}`,
+  })
+
+  return listOfPullRequests[0]?.number
+}
+
+/**
+ * When this file was first created, we only introduced support for creating a pull request for some translation batch.
+ * However, some of our first workflow runs failed during the pull request creation due to a timeout error.
+ * There have been cases where, despite the timeout error, the pull request gets created _anyway_.
+ * To accommodate this reality, we created this function to look for an existing pull request before a new one is created.
+ * Although the "find" check is redundant in the first "cycle", it's designed this way to recursively call the function again via its retry mechanism should that be necessary.
+ *
+ * @param {object} config Configuration options for creating the pull request.
+ * @returns {Promise<number>} The PR number.
+ */
+async function findOrCreatePullRequest(config) {
+  const found = await findPullRequestNumber(config)
+
+  if (found) {
+    return found
+  }
+
+  try {
+    const { data: pullRequest } = await octokit.rest.pulls.create({
+      owner: config.owner,
+      repo: config.repo,
+      base: config.base,
+      head: config.head,
+      title: config.title,
+      body: config.body,
+      draft: false,
+    })
+
+    return pullRequest.number
+  } catch (error) {
+    if (!error.response || !config.retryCount) {
+      throw error
+    }
+
+    if (!config.retryStatuses.includes(error.response.status)) {
+      throw error
+    }
+
+    console.error(`Error creating pull request: ${error.message}`)
+    console.warn(`Retrying in 5 seconds...`)
+    await new Promise((resolve) => setTimeout(resolve, 5000))
+
+    config.retryCount -= 1
+
+    return findOrCreatePullRequest(config)
+  }
+}
+
+/**
+ * @param {object} config Configuration options for labeling the PR
+ * @returns {Promise<undefined>}
+ */
+async function labelPullRequest(config) {
+  await octokit.rest.issues.update({
+    owner: config.owner,
+    repo: config.repo,
+    issue_number: config.issue_number,
+    labels: config.labels,
+  })
+}
+
+async function main() {
+  const options = {
+    title: TITLE,
+    base: BASE,
+    head: HEAD,
+    body: fs.readFileSync(BODY_FILE, 'utf8'),
+    labels: ['translation-batch', `translation-batch-${LANGUAGE}`],
+    owner: OWNER,
+    repo: REPO,
+    retryStatuses: RETRY_STATUSES,
+    retryCount: RETRY_ATTEMPTS,
+  }
+
+  options.issue_number = await findOrCreatePullRequest(options)
+  const pr = `${GITHUB_REPOSITORY}#${options.issue_number}`
+  console.log(`Created PR ${pr}`)
+
+  // metadata parameters aren't currently available in `github.rest.pulls.create`,
+  // but they are in `github.rest.issues.update`.
+  await labelPullRequest(options)
+  console.log(`Updated ${pr} with these labels: ${options.labels.join(', ')}`)
+}
+
+main()

.github/actions-scripts/enterprise-server-issue-templates/release-issue.md

@@ -12,13 +12,13 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
   - [ ] Increment the `next` variable above the `supported` array (e.g., new release number + `.1`).
   - [ ] Increment the `nextNext` variable above the `supported` array (e.g., new release number + `.2`).
 - [ ] Update the GHES dates file:
-  - [ ] Make sure you have a `.env` file at the root directory of your local checkout, and that it contains a PAT in the format of `GITHUB_TOKEN=<token>`.
+  - [ ] Make sure you have a `.env` file at the root directory of your local checkout, and that it contains a PAT in the format of `GITHUB_TOKEN=<token>` with `repo` scope. Ensure the PAT is SSO-enabled for the `github` org.
   - [ ] Run the script to update the dates file:
 
     ```
     script/update-enterprise-dates.js
     ```
-- [ ] Create REST files based on previous version:
+- [ ] Create REST files based on previous version. For example `script/enterprise-server-releases/create-rest-files.js --oldVersion [email protected] --newVersion [email protected]`:
 
   ```
   script/enterprise-server-releases/create-rest-files.js --oldVersion <PLAN@RELEASE> --newVersion <PLAN@RELEASE>
@@ -33,7 +33,7 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
   ```
   script/enterprise-server-releases/create-webhook-files.js --oldVersion <PLAN@RELEASE> --newVersion <PLAN@RELEASE>
   ```
-- [ ] Create a placeholder release notes file called `data/release-notes/<PRODUCT>/<RELEASE NUMBER>/PLACEHOLDER.yml`. For example `data/release-notes/3-1/PLACEHOLDER.yml`. Add the following placeholder content to the file:
+- [ ] Create a placeholder release notes file called `data/release-notes/<PRODUCT>/<RELEASE NUMBER>/PLACEHOLDER.yml`. For example `data/release-notes/enterprise-server/3-1/PLACEHOLDER.yml`. Add the following placeholder content to the file:
 
   ```
   date: '2021-05-04'
@@ -55,6 +55,8 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
   script/enterprise-server-releases/release-banner.js --action create --version <PLAN@RELEASE>
   ```
 
+- [ ] Create a PR with the above changes. This PR is used to track all docs changes and smoke tests associated with the release. For example https://github.com/github/docs-internal/pull/22286.
+
 ### When the `docs-internal` release branch is open
 
 - [ ] Add a label to the PR in this format:
@@ -102,7 +104,7 @@ This file should be automatically updated, but you can also run `script/update-e
   Usually, we should smoke test any new GHES admin guides, any large features landing in this GHES version for the first time, and the REST and GraphQL API references.
 - [ ] Alert the Neon Squad (formally docs-ecosystem team)  1-2 days before the release to deploy to `github/github`. A PR should already be open in `github/github`, to change `published` to `true` in  `app/api/description/config/releases/ghes-<NEXT RELEASE NUMBER>.yaml`. They will need to:
   - [ ] Get the required approval from `@github/ecosystem-api-reviewers` then deploy the PR to dotcom. This process generally takes 30-90 minutes.
-  - [ ] Once the PR merges, make sure that the auto-generated PR titled "Update OpenAPI Descriptions" in doc-internal contains both the derefrenced and decorated JSON files for the new GHES release. If everything looks good, merge the "Update OpenAPI Description" PR into the GHES release megabranch.
+  - [ ] Once the PR merges, make sure that the auto-generated PR titled "Update OpenAPI Descriptions" in doc-internal contains both the derefrenced and decorated JSON files for the new GHES release. If everything looks good, merge the "Update OpenAPI Description" PR into the GHES release megabranch. **Note:** Be careful about resolving the conflicts correctly—you may wish to delete the existing OpenAPI files for the release version from the megabranch, so there are no conflicts to resolve and to ensure that the incoming artifacts are the correct ones.
   - [ ] Add a blocking review to the auto-generated "Update OpenAPI Descriptions" PR in the public REST API description. (Remove this blocking review once the GHES release ships.)
 - [ ] [Freeze the repos](https://github.com/github/docs-content/blob/main/docs-content-docs/docs-content-workflows/freezing.md) at least 1-2 days before the release, and post an announcement in Slack so everybody knows.
 
@@ -113,8 +115,9 @@ This file should be automatically updated, but you can also run `script/update-e
 
   Use admin permissions to ship the release branch with this failure. Make sure that the merge's commit title does not include anything like `[DO NOT MERGE]`, and remove all the branch's commit details from the merge's commit message except for the co-author list.
 - [ ] Do any required smoke tests listed in the opening post in the megabranch PR.
-- [ ] Push the search index LFS objects for the public `github/docs` repo. The LFS objects were already being pushed for the internal repo after the `sync-english-index-for-<PLAN@RELEASE>` was added to the megabranch. To push the LFS objects, run the [search sync workflow](https://github.com/github/docs-internal/actions/workflows/sync-search-indices.yml) with the following inputs:
+- [ ] Once smoke tests have passed, you can [unfreeze the repos](https://github.com/github/docs-content/blob/main/docs-content-docs/docs-content-workflows/freezing.md) and post an announcement in Slack.
+- [ ] After unfreezing, push the search index LFS objects for the public `github/docs` repo. The LFS objects were already being pushed for the internal repo after the `sync-english-index-for-<PLAN@RELEASE>` was added to the megabranch. To push the LFS objects, run the [search sync workflow](https://github.com/github/docs-internal/actions/workflows/sync-search-indices.yml) with the following inputs:
   version: `enterprise-server@<RELEASE>`
   language: `en`
-- [ ] Once smoke tests have passed, you can [unfreeze the repos](https://github.com/github/docs-content/blob/main/docs-content-docs/docs-content-workflows/freezing.md) and post an announcement in Slack.
-- [ ] After the release, in the `docs-content` repo, add the now live version number to the "Specific GHES version(s)" section in the following files: [`.github/ISSUE_TEMPLATE/release-tier-1-or-2-tracking.yml`](https://github.com/github/docs-content/blob/main/.github/ISSUE_TEMPLATE/release-tier-1-or-2-tracking.yml) and [`.github/ISSUE_TEMPLATE/release-tier-3-or-tier-4.yml`](https://github.com/github/docs-content/blob/main/.github/ISSUE_TEMPLATE/release-tier-3-or-tier-4.yml). When the PR is approved, merge it in. 
+- [ ] After unfreezing, if there were significant or highlighted GraphQL changes in the release, consider manually running the [GraphQL update workflow](https://github.com/github/docs-internal/actions/workflows/update-graphql-files.yml) to update our GraphQL schemas. By default this workflow only runs once every 24 hours.
+- [ ] After the release, in the `docs-content` repo, add the now live version number to the "Specific GHES version(s)" section in the following files: [`.github/ISSUE_TEMPLATE/release-tier-1-or-2-tracking.yml`](https://github.com/github/docs-content/blob/main/.github/ISSUE_TEMPLATE/release-tier-1-or-2-tracking.yml) and [`.github/ISSUE_TEMPLATE/release-tier-3-or-tier-4.yml`](https://github.com/github/docs-content/blob/main/.github/ISSUE_TEMPLATE/release-tier-3-or-tier-4.yml). When the PR is approved, merge it in.