From bdf724c922efd29e8f9dcfc5764e1ca22c3731b3 Mon Sep 17 00:00:00 2001 From: Rachael Sewell Date: Tue, 15 Jun 2021 15:07:15 -0700 Subject: [PATCH 1/2] Update a few enterprise release steps (#19072) --- .../create-enterprise-issue.js | 6 ++- .../release-issue.md | 52 +++++++++++++++++-- package.json | 1 + .../create-graphql-files.js | 11 ++++ 4 files changed, 63 insertions(+), 7 deletions(-) diff --git a/.github/actions-scripts/create-enterprise-issue.js b/.github/actions-scripts/create-enterprise-issue.js index d726c0d7e7a4..a640e4b7d0b0 100755 --- a/.github/actions-scripts/create-enterprise-issue.js +++ b/.github/actions-scripts/create-enterprise-issue.js @@ -40,6 +40,8 @@ async function run () { process.exit(1) } + const repoToOpenIssue = milestone === 'release' ? 'docs-content' : 'docs-engineering' + // Milestone-dependent values. const numberOfdaysBeforeMilestoneToOpenIssue = milestone === 'release' ? numberOfdaysBeforeReleaseToOpenIssue @@ -71,7 +73,7 @@ async function run () { } 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 issueLabels = [`enterprise ${milestone}`] const issueTitle = `[${nextMilestoneDate}] Enterprise Server ${versionNumber} ${milestone} (technical steps)` const issueBody = `GHES ${versionNumber} ${milestone} occurs on ${nextMilestoneDate}. @@ -85,7 +87,7 @@ async function run () { try { issue = await octokit.request('POST /repos/{owner}/{repo}/issues', { owner: 'github', - repo: 'docs-internal', + repo: repoToOpenIssue, title: issueTitle, body: issueBody, labels: issueLabels diff --git a/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md b/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md index 9f5120f6e2fd..ce34b8f0077e 100644 --- a/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md +++ b/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md @@ -21,6 +21,25 @@ ``` script/enterprise-server-release/create-webhook-files.js --oldVersion --newVersion ``` +- [ ] Create a placeholder release notes file called `data/release-notes//PLACEHOLDER.yml`. For example `data/release-notes/3-1/PLACEHOLDER.yml`. Add the following placeholder content to the file: + ``` + date: '2021-05-04' + release_candidate: true + deprecated: false + intro: PLACEHOLDER + sections: + bugs: + - PLACEHOLDER + known_issues: + - PLACEHOLDER + ``` + **Note:** All of the content in this file will be updated when the release notes are created in the megabranch including the filename `PLACEHOLDER.yml`. You can update the date or leave it as-is and wait to update it when the release notes are finalized. +- [ ] Create the Algolia search indices for the new release: + ``` + npm run sync-search-ghes-release + ``` + + Check in the updated `lib/search/cached-index-names.json`. - [ ] (Optional) Add a Release Candidate banner: ``` script/enterprise-server-releases/release-banner.js --action create --version @@ -39,17 +58,40 @@ - [ ] 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-.yaml app/api/description/config/releases/ghes-.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. + - [ ] Update `published` in that file to `false`. **Note:** This is important to ensure that changes for the next version of the OpenAPI schema changes are not made public until the new version is released. + - [ ] Create a second PR based on the PR created ☝️ that toggles `published` to `true` in the `app/api/description/config/releases/ghes-.yaml` file. When this PR merges it will publish the new release to the `github/rest-api-description` repo and will trigger a pull request in the `github/docs-internal` repo with the schemas for the next GHES release. There is a step in this list to merge that PR in the "Before shipping the release branch" section. + +### Maintaining this template + +- [ ] If you notice that any of these steps become out-of-date, open a pull request to update this [issue template](https://github.com/github/docs-internal/blob/main/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md). -#### Troubleshooting +### Troubleshooting -If the `OpenAPI dev mode check / check-schema-versions` check fails on the release branch, in your local checkout of the mega branch: +#### `OpenAPI dev mode check / check-schema-versions` failures + +If the `OpenAPI dev mode check / check-schema-versions` check fails with the following message: +> :construction::warning: Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. For more information, see 'script/rest/README.md' - run `git checkout origin/main lib/rest/static/*` -- run `script/rest/update-files.js --decorate-only` +- run `script/enterprise-server-releases/create-rest-files.js --oldVersion enterprise-server@ --newVersion enterprise-server@` - push the resulting changes +#### `Node.js tests / test content` failures + +If the `Node.js tests / test content` check fails with the following message, the `lib/enterprise-dates.json` file is not up-to-date: +> FAIL tests/content/algolia-search.js ● algolia › has remote indexNames in every language for every supported GHE version + +This file should be automatically updated, but you can also run `script/update-enterprise-dates.js` to update it. **Note:** If the test is still failing after running this script, look at the dates for this release. If the date is still inaccurate, it may be an issue with the source at https://github.com/github/enterprise-releases/blob/master/docs/supported-versions.md#release-lifecycle-dates. If that is the case, manually update the dates in the `lib/enterprise-dates.json` file. + ### 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: '<='` -- [ ] In `github/github`, open a PR to change `published` to `true` in `app/api/description/config/releases/ghes-.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. +- [ ] 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-.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. + - [ ] 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.) + +### 🚢 🛳️ 🚢 Shipping the release branch + +- [ ] The `github/docs-internal` repo is frozen, and the `Repo Freeze Check / Prevent merging during deployment freezes (pull_request_target)` test is expected to fail. Use admin permissions to ship the release branch with this failure. +- [ ] Once smoke tests have passed, you can unfreeze the repos by deleting the `FREEZE` secret in both the `github/docs-internal` and `github/docs` repos. To delete the secrets, click the repo **Settings** tab and then click **Secrets** in the left sidebar. Click **Remove** next to the `FREEZE` secret. \ No newline at end of file diff --git a/package.json b/package.json index 2a48368f2c9c..1ac1654a6a58 100644 --- a/package.json +++ b/package.json @@ -201,6 +201,7 @@ "browser-test-server": "cross-env NODE_ENV=production PORT=4001 node server.js", "browser-test-tests": "cross-env BROWSER=1 jest tests/browser/browser.js", "sync-search": "start-server-and-test sync-search-server 4002 sync-search-indices", + "sync-search-ghes-release": "GHES_RELEASE=1 start-server-and-test sync-search-server 4002 sync-search-indices", "sync-search-dry-run": "DRY_RUN=1 npm run sync-search", "sync-search-server": "cross-env NODE_ENV=production PORT=4002 node server.js", "sync-search-indices": "script/sync-search-indices.js", diff --git a/script/enterprise-server-releases/create-graphql-files.js b/script/enterprise-server-releases/create-graphql-files.js index 544783e2f545..42c969fe6cd7 100755 --- a/script/enterprise-server-releases/create-graphql-files.js +++ b/script/enterprise-server-releases/create-graphql-files.js @@ -51,19 +51,24 @@ if (!fs.existsSync(newSchemaFile)) { const previewsFile = path.join(graphqlStaticDir, 'previews.json') const changesFile = path.join(graphqlStaticDir, 'upcoming-changes.json') const objectsFile = path.join(graphqlStaticDir, 'prerendered-objects.json') +const inputObjectsFile = path.join(graphqlStaticDir, 'prerendered-input-objects.json') const previews = require(previewsFile) const changes = require(changesFile) const objects = require(objectsFile) +const inputObjects = require(inputObjectsFile) // The prerendered objects file for the "old version" contains hardcoded links with the old version number. // We need to update those links to include the new version to prevent a test from failing. const regexOldVersion = new RegExp(oldVersion, 'gi') const stringifiedObject = JSON.stringify(objects[oldVersionId]) .replace(regexOldVersion, newVersion) +const stringifiedInputObject = JSON.stringify(inputObjects[oldVersionId]) + .replace(regexOldVersion, newVersion) previews[newVersionId] = previews[oldVersionId] changes[newVersionId] = changes[oldVersionId] objects[newVersionId] = JSON.parse(stringifiedObject) +inputObjects[newVersionId] = JSON.parse(stringifiedInputObject) // check that it worked if (!Object.keys(previews).includes(newVersionId)) { @@ -81,10 +86,16 @@ if (!Object.keys(objects).includes(newVersionId)) { process.exit(1) } +if (!Object.keys(inputObjects).includes(newVersionId)) { + console.log(`Error! Can't find ${newVersionId} in ${inputObjectsFile}.`) + process.exit(1) +} + // write the new files fs.writeFileSync(previewsFile, JSON.stringify(previews, null, 2)) fs.writeFileSync(changesFile, JSON.stringify(changes, null, 2)) fs.writeFileSync(objectsFile, JSON.stringify(objects, null, 2)) +fs.writeFileSync(inputObjectsFile, JSON.stringify(inputObjects, null, 2)) // now create the new version directory in data/graphql const srcDir = path.join(graphqlDataDir, oldVersionId) From 70256b0e6aa2a750d9811133b5b004b445efa6d0 Mon Sep 17 00:00:00 2001 From: Mike Surowiec Date: Tue, 15 Jun 2021 15:19:25 -0700 Subject: [PATCH 2/2] fix: sometimes there are no childPages, such as /es/github-ae@latest/admin (#19944) --- components/product/SidebarProduct.tsx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/product/SidebarProduct.tsx b/components/product/SidebarProduct.tsx index c2697d77dbba..02c128206b8f 100644 --- a/components/product/SidebarProduct.tsx +++ b/components/product/SidebarProduct.tsx @@ -108,10 +108,10 @@ const CollapsibleSection = (props: SectionProps) => { - {!hideChildren && ( + {!hideChildren && page.childPages.length > 0 && ( <> {/* */} - {page.childPages[0].page.documentType === 'mapTopic' ? ( + {page.childPages[0]?.page.documentType === 'mapTopic' ? (
    {page.childPages.map((childPage, i) => { const childTitle = childPage.renderedShortTitle || childPage.renderedFullTitle @@ -165,7 +165,7 @@ const CollapsibleSection = (props: SectionProps) => { ) })}
- ) : page.childPages[0].page.documentType === 'article' ? ( + ) : page.childPages[0]?.page.documentType === 'article' ? (
    {/* */} {page.childPages.map((childPage, i, arr) => {