update deprecation steps for re-scraping content (#33295)

Co-authored-by: Robert Sese <[email protected]>
Co-authored-by: Matt Pollard <[email protected]>

Author: 3 people

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

@@ -9,7 +9,7 @@ The following large repositories are used throughout this checklist, it may be u
 - `github/github`
 - `github/docs-internal`
 
-Additionally, you may want to download:
+Additionally, download:
 
 - [Azure Storage Explorer](https://aka.ms/portalfx/downloadstorageexplorer)
 
@@ -40,7 +40,7 @@ Additionally, you may want to download:
 
   **Note:** You can pass the `--dry-run` flag to scrape only the first 10 pages plus their redirects for testing purposes. **If you use the dry run command, be sure to run the full script without `--dry-run` before you commit the changes.**
 
-## Step 3: Manually remove the search input from the archived docs
+## Step 2: Manually remove the search input from the archived docs
 
 - [ ] Search for `site-search-input` in the compressed Javascript files (should find the file in the `_next` directory). When you find it, use something like https://beautifier.io/ or VSCode to reformat it to be readable. To reformat using VSCode, use the "Format document" option or <kbd>Shift</kbd>+<kbd>Option</kbd>+<kbd>F</kbd>. Find `site-search-input` in the file, the result will be enclosed in a function that looks something like... `(0,f.jsx)("input",{"data-testid":"site-search-input",` Delete the entire function. For example, this:
   ```
@@ -88,7 +88,7 @@ Additionally, you may want to download:
   ```
 - [ ] Save the file. If using beautifier, copy and paste the updated file back into your temp directory with the scraped archive content.
 
-## Step 2: Upload the scraped content directory to Azure storage
+## Step 3: Upload the scraped content directory to Azure storage
 
 - [ ] Log in to the Azure portal from Okta. Navigate to the [githubdocs Azure Storage Blob resource](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.
@@ -97,7 +97,11 @@ Additionally, you may want to download:
 - [ ] Check the log to ensure all files were uploaded successfully.
 - [ ] Remove the temporarily created directory from your `github/docs-internal` checkout.
 
-## Step 4: Deprecate the version in docs-internal
+## Step 4: Create a tag and long-running branch
+
+Create a new tag for the most recent commit on the `main` branch so that we can keep track of where in commit history we removed the GHES release. Create a tag called `enterprise-<release number>-release`. Then from that commit on `main` create a new branch called `enterprise-<release number>-release`. This branch will be long-lived and used to rerender and scrape content that is added after a release is deprecated.
+
+## Step 5: Deprecate the version in docs-internal
 
 In your `docs-internal` checkout:
 
@@ -111,7 +115,7 @@ You can test that the static pages were generated correctly on localhost and on
 
 Poke around several pages, ensure that the stylesheets are working properly, images are rendering properly, and that the search functionality was disabled.
 
-## Step 5: Remove static files for the version
+## Step 6: Remove static files for the version
 
 **Note:** We do not remove the old content for GHES release notes. New release notes can be added after we perform a deprecation in some rare cases, and not removing this content makes it easier for us to re-scrape the content to add to Azure Blob Storage.
 
@@ -121,7 +125,7 @@ Poke around several pages, ensure that the stylesheets are working properly, ima
 - [ ] Open a new PR.
 - [ ] Get a review from docs-engineering and merge. This step can be merged independently from step 6. The purpose of splitting up steps 5 and 6 is to focus the review on specific files.
 
-## Step 6: Remove the liquid conditionals and content for the version
+## Step 7: Remove the liquid conditionals and content for the version
 
 - [ ] In your `docs-internal` checkout, create a new branch `remove-<version>-markup` branch: `git checkout -b remove-<version>-markup` (you can branch off of `main` or from your `deprecate-<version>` branch, up to you).
 - [ ] Remove the outdated Liquid markup and frontmatter.
@@ -131,17 +135,31 @@ Poke around several pages, ensure that the stylesheets are working properly, ima
   - [ ] Debug any test failures or unexpected results -- it's very likely manual updates will be necessary, the script does a lot of work but doesn't automate everything and can't 100% replace human intent.
 - [ ] When the PR is approved, merge it in to complete the deprecation. This can be merged independently from step 5.
 
-## Step 7: Deprecate the OpenAPI description in `github/github`
+## Step 8: Deprecate the OpenAPI description in `github/github`
 
 - [ ] In `github/github`, edit the release's config file in `app/api/description/config/releases/`, and change `deprecated: false` to `deprecated: true`.
 - [ ] Open a new PR, and get the required code owner approvals. A docs-content team member can approve it for the docs team.
 - [ ] When the PR is approved, [deploy the `github/github` PR](https://thehub.github.com/epd/engineering/devops/deployment/deploying-dotcom/). If you haven't deployed a `github/github` PR before, work with someone that has -- the process isn't too involved depending on how you deploy, but there are a lot of details that can potentially be confusing as you can see from the documentation.
 
 **Note**: you can do this step independently of the other steps after a GHES version is deprecated since it should no longer get updates in github/github. You should plan to get this PR merged as soon as possible, otherwise if you wait too long our OpenAPI automation may re-add the static files that you removed in step 5.
 
-## Step 5: Continue to deprecate the version in docs-internal
+## Step 9: Continue to deprecate the version in docs-internal
 
 - [ ] Open a new PR. Make sure to check the following:
   - [ ] Tests are passing (you may need to include the changes in step 6 to get tests to pass).
   - [ ] The deprecated version renders in preview as expected. You should be able to navigate to `docs.github.com/enterprise/<DEPRECATED VERSION>` to access the docs. You should also be able to navigate to a page that is available in the deprecated version and change the version in the URL to the deprecated version, to test redirects.
-  - [ ] The new oldest supported version renders on staging as expected. You should see a banner on the top of every page for the oldest supported version that notes when the version will be deprecated.
+  - [ ] The new oldest supported version renders on staging as expected. You should see a banner on the top of every page for the oldest supported version that notes when the version will be deprecated.
+
+## Re-scraping a page or all pages
+
+Occasionally, a change will need to be added to our archived enterprise versions. If this occurs, you can check out the `enterprise-<release number>-release` branch and re-scrape the page or all pages using `script/enterprise-server-deprecations/archive-version.js`. To scrape a single page you can use the `—page <page relative path>` option.
+
+For each language, upload the new file to Azure blob storage in the `enterprise` container.
+
+After uploading the new files, you will need to purge the Fastly cache for the single page. From Okta, go to Fastly and select `docs`. Click `Purge` then `Purge URL`. If you need to purge a whole path, just do a `Purge All`
+
+![](/assets/images/fastly_purge.jpg)
+
+Enter the URL or path and do a soft purge.
+
+![](/assets/images/fastly_purge_url.jpg)

assets/images/fastly_purge.jpg

@@ -2,6 +2,15 @@
 
 Rendered here: https://docs.github.com/en/enterprise-server@latest/admin/release-notes
 
+## Adding release notes to a deprecated GitHub Enterprise Server release
+
+During the deprecation of a GitHub Enterprise Server release per [this issue template](/.github/actions-scripts/enterprise-server-issue-templates/deprecation-issue.md), Docs Engineering removes the YAML files with the version's release notes from `github/docs-internal`.
+
+If a stakeholder requests an update to deprecated release notes, you can update the notes by completing the following steps.
+
+1. Check out the long-running branch <code>enterprise-<em>VERSION</em>-release</code> and create a PR to update the release notes for the deprecated version on that branch.
+2. Reach out to #docs-engineering to request a re-scrape and update of the content stored in Azure. See the section about re-scraping content in the [deprecation checklist](/.github/actions-scripts/enterprise-server-issue-templates/deprecation-issue.md).
+
 ## How it works
 
 ### Placeholder content file