Merge branch 'main' into site-policy-sync-update

Author: pcihon

.github/ISSUE_COMMENT_TEMPLATE/quick-status.yml

@@ -0,0 +1,29 @@
+---
+name: A brief status update
+description: A brief status update.
+body:
+  - type: dropdown
+    attributes:
+      label: Status
+      options:
+        - label: 'GREY ⚪️ (Not started, paused, not currently being worked on)'
+          value: 'Status: GREY'
+        - label: 'GREEN 🟢 (All good, smooth sailing)'
+          value: 'Status: GREEN'
+        - label: "YELLOW \U0001F7E1 (On track, with hurdles to work through)"
+          value: 'Status: YELLOW'
+        - label: "RED \U0001F534 (BLOCKED)"
+          value: 'Status: RED'
+        - label: "BLACK ⚫️ (We shipped it \U0001F389)"
+          value: 'Status: BLACK'
+  - type: textarea
+    attributes:
+      label: Update Summary
+      placeholder:
+        Brief summary of the status and next steps. Any blockers should be
+        called out specifically.
+  - type: input
+    attributes:
+      label: 'Attribution'
+      value: '_created with :heart: by typing_ `/status`'
+      format: text

.github/ISSUE_COMMENT_TEMPLATE/status.yml

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const github = require('@actions/github')
+const core = require('@actions/core')
+
+async function run () {
+  const token = process.env.GITHUB_TOKEN
+  const octokit = github.getOctokit(token)
+  const query = encodeURIComponent('is:open repo:github/docs-internal is:issue')
+  
+  const deprecationIssues = await octokit.request(`GET /search/issues?q=${query}+label:"enterprise%20deprecation"`)
+  const releaseIssues = await octokit.request(`GET /search/issues?q=${query}+label:"enterprise%20release"`)
+  const isDeprecationIssue = deprecationIssues.data.items.length === 0 ? 'false' : 'true'
+  const isReleaseIssue = releaseIssues.data.items.length === 0 ? 'false' : 'true'
+  core.setOutput('deprecationIssue', isDeprecationIssue)
+  core.setOutput('releaseIssue', isReleaseIssue)
+  return `Set outputs deprecationIssue: ${isDeprecationIssue}, releaseIssue: ${isReleaseIssue}`
+}
+
+run()
+  .then(
+    (response) => { console.log(`Finished running: ${response}`) },
+    (error) => {
+      console.log(`#ERROR# ${error}`)
+      process.exit(1)
+    }
+  )

.github/ISSUE_COMMENT_TEMPLATE/target-date.yml

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const github = require('@actions/github')
+const enterpriseDates = require('../../lib/enterprise-dates')
+const { latest, oldestSupported } = require('../../lib/enterprise-server-releases')
+const acceptedMilestones = ['release', 'deprecation']
+const teamsToCC = '/cc @github/docs-content @github/docs-engineering'
+
+// Adjust these values as needed.
+const numberOfdaysBeforeReleaseToOpenIssue = 30
+const numberOfdaysBeforeDeprecationToOpenIssue = 15
+
+// [start-readme]
+//
+// This script runs once per day via a scheduled GitHub Action to check whether
+// an Enterprise release or deprecation milestone is within the specified
+// number of days.
+//
+// When a milestone is within the specified number of days, a new issue is
+// created using the templates in 
+// .github/actions-scripts/enterprise-server-issue-templates. 
+//
+// Release issues are then added to the docs content squad board for triage.
+// Deprecations issues are owned by docs engineering and are added to the 
+// docs engineering squad board automatically when the engineering label is added.
+//
+// [end-readme]
+
+run()
+
+async function run () {
+  
+
+  const milestone = process.argv[2]
+  if (!acceptedMilestones.includes(milestone)) {
+    console.log('Please specify either \'release\' or \'deprecation\'\n')
+    console.log('Example: script/open-enterprise-issue.js release')
+    process.exit(1)
+  }
+
+  // Milestone-dependent values.
+  const numberOfdaysBeforeMilestoneToOpenIssue = milestone === 'release'
+    ? numberOfdaysBeforeReleaseToOpenIssue
+    : numberOfdaysBeforeDeprecationToOpenIssue
+
+  const versionNumber = milestone === 'release'
+    ? getNextVersionNumber()
+    : oldestSupported
+
+  if (!versionNumber) {
+    console.log(`Could not find the next version number after ${latest} in enterprise-dates.json. Try running script/udpate-enterprise-dates.js, then rerun this script.`)
+    process.exit(0)
+  }
+
+  const datesForVersion = enterpriseDates[versionNumber]
+
+  if (!datesForVersion) {
+    console.log(`Could not find ${versionNumber} in enterprise-dates.json. Try running script/udpate-enterprise-dates.js, then rerun this script.`)
+    process.exit(0)
+  }
+
+  const nextMilestoneDate = datesForVersion[`${milestone}Date`]
+  const daysUntilMilestone = calculateDaysUntilMilestone(nextMilestoneDate)
+
+  // If the milestone is more than the specific days away, exit now.
+  if (daysUntilMilestone > numberOfdaysBeforeMilestoneToOpenIssue) {
+    console.log(`The ${versionNumber} ${milestone} is not until ${nextMilestoneDate}! An issue will be opened when it is ${numberOfdaysBeforeMilestoneToOpenIssue} days away.`)
+    process.exit(0)
+  }
+
+  const milestoneSteps = fs.readFileSync(path.join(process.cwd(), `.github/actions-scripts/enterprise-server-issue-templates/${milestone}-issue.md`), 'utf8')
+  const issueLabels = [`enterprise ${milestone}`, `engineering`]
+  const issueTitle = `[${nextMilestoneDate}] Enterprise Server ${versionNumber} ${milestone} (technical steps)`
+
+  const issueBody = `GHES ${versionNumber} ${milestone} occurs on ${nextMilestoneDate}.
+  \n${milestoneSteps}
+  ${teamsToCC}`
+
+  const token = process.env.GITHUB_TOKEN
+
+  // Create the milestone issue
+  const octokit = github.getOctokit(token)
+  try {
+    issue = await octokit.request('POST /repos/{owner}/{repo}/issues', {
+      owner: 'github',
+      repo: 'docs-internal',
+      title: issueTitle,
+      body: issueBody,
+      labels: issueLabels
+    })
+    if (issue.status === 201) {
+      // Write the values to disk for use in the workflow.
+      console.log(`Issue #${issue.data.number} for the ${versionNumber} ${milestone} was opened: ${issue.data.html_url}`)
+    }
+  } catch (error) {
+    console.error(`#ERROR# ${error}`)
+    console.log(`🛑 There was an error creating the issue.`)
+    process.exit(1)
+  }
+
+  // Add the release issue to the 'Needs triage' column on the 
+  // docs content squad project board:
+  // https://github.com/orgs/github/projects/1773#column-12198119
+  // Deprecation issues are owned by docs engineering only and will
+  // be triaged by adding the engineering label to the issue.
+  if (milestone === 'release') {
+    try {
+      const addCard = await octokit.request('POST /projects/columns/{column_id}/cards', {
+        column_id: 12198119, 
+        content_id: issue.data.id,
+        content_type: 'Issue',
+        mediaType: {
+          previews: [
+            'inertia'
+          ]
+        }
+      })
+
+      if (addCard.status === 201) {
+        // Write the values to disk for use in the workflow.
+        console.log(`The issue #${issue.data.number} was added to https://github.com/orgs/github/projects/1773#column-12198119.`)
+      } 
+    } catch(error) {
+      console.error(`#ERROR# ${error}`)
+      console.log(`🛑 There was an error adding the issue to the project board.`)
+      process.exit(1)
+    }
+  }
+}
+
+function getNextVersionNumber () {
+  const indexOfLatest = Object.keys(enterpriseDates).indexOf(latest)
+  const indexOfNext = indexOfLatest + 1
+  return Object.keys(enterpriseDates)[indexOfNext]
+}
+
+function calculateDaysUntilMilestone (nextMilestoneDate) {
+  const today = new Date().toISOString().slice(0, 10)
+  const differenceInMilliseconds = getTime(nextMilestoneDate) - getTime(today)
+  // Return the difference in days
+  return Math.floor((differenceInMilliseconds) / (1000 * 60 * 60 * 24))
+}
+
+function getTime (date) {
+  return new Date(date).getTime()
+}

.github/actions-scripts/check-for-enterprise-issues-by-label.js

@@ -0,0 +1,57 @@
+## Overview
+
+The day after a GHES version's [deprecation date](https://github.com/github/docs-internal/tree/main/lib/enterprise-dates.json), a banner on the docs will say: `This version was deprecated on <date>.` This is all users need to know. However, we don't want to update those docs anymore or link to them in the nav.  Follow the steps in this issue to **archive** the docs.
+
+**Note**: Do each step below in a separate PR. Only move on to the next step when the previous PR has been merged.
+
+## Step 1: Scrape the docs and archive the files
+
+- [ ] In your checkout of the [repo with archived GHES content](https://github.com/github/help-docs-archived-enterprise-versions), create a new branch: `git checkout -b deprecate-<version>`
+- [ ] In your `docs-internal` checkout, download the static files for the oldest supported version into your archival checkout:
+    ```
+    $ script/enterprise-server-deprecations/archive-version.js -p <path-to-archive-repo-checkout>
+    ```
+    If your checkouts live in the same directory, this command would be:
+    ```
+    $ script/enterprise-server-deprecations/archive-version.js -p ../help-docs-archived-enterprise-versions
+    ```
+    **Note:** You can pass the `--dry-run` flag to scrape only the first 10 pages plus their redirects for testing purposes.
+  
+## Step 2: Upload the assets directory to Azure storage
+
+- [ ] Log in to the Azure portal from Okta. Navigate to the [githubdocs Azure Storage Blob resoruce](https://portal.azure.com/#@githubazure.onmicrosoft.com/resource/subscriptions/fa6134a7-f27e-4972-8e9f-0cedffa328f1/resourceGroups/docs-production/providers/Microsoft.Storage/storageAccounts/githubdocs/overview).
+- [ ] Click the "Open in Explorer" button to the right of search box.If you haven't already, click the download link to download "Microsoft Azure Storage Explorer." To login to the app, click the plug icon in the left sidebar and click the option to "add an azure account." When you login, you'll need a yubikey to authenticate through Okta.
+- [ ] From the Microsoft Azure Storage Explorer app, select the `githubdocs` storage account resource and navigate to the `github-images` blob container. 
+- [ ] Click "Upload" and select "Upload folder." Click the "Selected folder" input to navigate to the `help-docs-archived-enterprise-versions` repository and select the `assets` directory for the version you just generated. In the "Destination folder" input, add the version number. For example, `/enterprise/2.22/`.
+- [ ] Check the log to ensure all files were uploaded successfully.
+- [ ] Removed the `assets` directory from the `/help-docsc-archived-enterprise-versions` repository.
+
+## Step 3: Commit and push changes to help-docs-archived-enterprise-versions repo
+
+- [ ] In your archival checkout, `git add <version>`, commit, and push.
+- [ ] Open a PR and merge it in. Note that the version will _not_ be deprecated on the docs site until you do the next step.
+
+## Step 4: Deprecate the version in docs-internal
+
+In your `docs-internal` checkout:
+- [ ] Create a new branch: `git checkout -b deprecate-<version>`.
+- [ ] Edit `lib/enterprise-server-releases.js` by moving the number to be deprecated into the `deprecated` array.
+- [ ] Run `script/enterprise-server-deprecations/remove-static-files.js` and commit results.
+- [ ] Manually remove entries for the deprecated version from `lib/redirects/static/developer-docs-routes-for-supported-versions.json`.
+    - **Note**: These entries only go up to 2.21. We can remove this step once 2.21 is deprecated.
+- [ ] Open a new PR. Make sure to check the following:
+    - [ ] Tests are passing.
+    - [ ] The deprecated version renders on staging as expected.
+    - [ ] The new oldest supported version renders on staging as expected. Also check the banner text.
+- [ ] When the PR is approved, merge it in to complete the deprecation.
+
+## Step 5: Remove outdated Liquid markup and frontmatter
+
+The following steps are somewhat optional and can be completed at any time. They do not have user impact; they just clear out old Liquid statements for the deprecated version, which makes things easier for content writers.
+
+In your `docs-internal` checkout:
+- [ ] Create a new branch: `git checkout -b remove-<version>-markup`
+- [ ] Run the script: `script/remove-deprecated-enterprise-version-markup.js --release <number>`.
+- [ ] Spot check a few changes. Content, frontmatter, and data files should all have been updated.
+- [ ] Open a PR with the results. The diff may be large and complex, so make sure to get a review from `@github/docs-content`.
+- [ ] Debug any test failures or unexpected results.

.github/actions-scripts/create-enterprise-issue.js

@@ -0,0 +1,55 @@
+## To enable the new version
+
+**Do these steps in a local checkout to create a GHES release branch with passing tests:**
+
+- [ ] In [lib/enterprise-server-releases.js](https://github.com/github/docs-internal/blob/main/lib/enterprise-server-releases.js):
+      - [ ] Prepend the new release number to the `supported` array.
+      - [ ] Increment the `next` variable above the `supported` array (e.g., new release number + `.1`)
+- [ ] Update the GHES dates file (requires a PAT in a local `.env` file):
+    ```
+    script/update-enterprise-dates.js
+    ```
+- [ ] Create REST files based on previous version:
+    ```
+    script/enterprise-server-releases/create-rest-files.js --oldVersion <PLAN@RELEASE> --newVersion <PLAN@RELEASE>
+    ```
+- [ ] Create GraphQL files based on previous version:
+    ```
+    script/enterprise-server-releases/create-graphql-files.js --oldVersion <PLAN@RELEASE> --newVersion <PLAN@RELEASE>
+    ```
+- [ ] Create webhook files based on previous version:
+    ```
+    script/enterprise-server-release/create-webhook-files.js --oldVersion <PLAN@RELEASE> --newVersion <PLAN@RELEASE>
+    ```
+- [ ] (Optional) Add a Release Candidate banner:
+    ```
+    script/enterprise-server-releases/release-banner.js --action create --version <PLAN@RELEASE>
+    ```
+
+### When the `docs-internal` release branch is open
+
+- [ ] Add a label to the PR in this format:
+    ```
+    sync-english-index-for-<PLAN@RELEASE>
+    ```
+    ☝️ This will run a workflow **on every push to the PR** that will sync **only** the English index for the new version to Algolia. This will make the GHES content searchable on staging throughout content creation, and will ensure the search updates go live at the same time the content is published. See [`contributing/search.md`](https://github.com/github/docs-internal/blob/main/contributing/search.md) for details.
+
+- [ ] In `github/github`, to create a new GHES release follow these steps:
+  - [ ] Copy the previous release's root document to a new root document for this release `cp app/api/description/ghes-<LATEST RELEASE NUMBER>.yaml app/api/description/ghes-<NEXT RELEASE NUMBER>.yaml`.
+  - [ ] Update the `externalDocs.url` property in that file to use the new GHES release number.
+  - [ ] Copy the previous release's configuration file to a new configuration file for this release `cp app/api/description/config/releases/ghes-<LATEST RELEASE NUMBER>.yaml app/api/description/config/releases/ghes-<NEXT RELEASE NUMBER>.yaml`.
+  - [ ] Update the `variables.externalDocsUrl`, `variables.ghesVersion`, and `patch.[].value.url` in that file to use the new GHES release number.
+  - [ ] Update `published` in that file to `false`. **Note:** This is important to ensure that 3.1 OpenAPI changes are not made public until 3.1 is released.
+
+#### Troubleshooting
+
+If the `OpenAPI dev mode check / check-schema-versions` check fails on the release branch, in your local checkout of the mega branch:
+
+- run `git checkout origin/main lib/rest/static/*`
+- run `script/rest/update-files.js --decorate-only`
+- push the resulting changes
+
+### Before shipping the release branch
+
+- [ ] Add the GHES release notes to `data/release-notes/` and update the versioning frontmatter in `content/admin/release-notes.md` to `enterprise-server: '<=<RELEASE>'`
+- [ ] In `github/github`, open a PR to change `published` to `true` in  `app/api/description/config/releases/ghes-<NEXT RELEASE NUMBER>.yaml`. Get the required approval from `@github/ecosystem-api-reviewers` then deploy to dotcom. This process generally takes 30-90 minutes. Ask in `#docs-ecosystem` if you need help with this.