Improve the GHES deprecation runbook and tooling (#61619)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

package.json

@@ -35,7 +35,7 @@
     "deleted-assets-pr-comment": "tsx src/assets/scripts/deleted-assets-pr-comment.ts",
     "deleted-features-pr-comment": "tsx src/data-directory/scripts/deleted-features-pr-comment.ts",
     "deprecate-ghes": "tsx src/ghes-releases/scripts/deprecate/index.ts",
-    "deprecate-ghes-archive": "cross-env NODE_OPTIONS=--max-old-space-size=16384 tsx src/ghes-releases/scripts/deprecate/archive-version.ts",
+    "deprecate-ghes-archive": "cross-env NODE_ENV=production NODE_OPTIONS=--max-old-space-size=16384 tsx src/ghes-releases/scripts/deprecate/archive-version.ts",
     "dev": "cross-env npm start",
     "dev-toc": "tsx src/dev-toc/generate.ts",
     "enable-automerge": "tsx src/workflows/enable-automerge.ts",

src/ghes-releases/lib/deprecation-steps.md

@@ -103,12 +103,13 @@ async function createDeprecationIssue() {
   const issueTemplate = readFileSync('src/ghes-releases/lib/deprecation-steps.md', 'utf8')
   const { data, content } = matter(issueTemplate)
   const { title, labels } = data
+  const renderedContent = content.replaceAll('{{ release-number }}', oldestSupported)
   const body = `GHES ${oldestSupported} deprecation occurs on ${deprecationDate}.
-  \n${content}
-  '/cc @github/docs-engineering'`
+
+${renderedContent}`
   await createIssue(
     repo,
-    title.replace('{{ release-number }}', oldestSupported),
+    title.replaceAll('{{ release-number }}', oldestSupported),
     body,
     labels,
     oldestSupported,

src/ghes-releases/lib/variable-example.png

@@ -112,6 +112,8 @@ async function main() {
       } catch (err) {
         console.error('scraping error')
         console.error(err)
+        server.close(() => process.exit(1))
+        return
       }
 
       fs.renameSync(
@@ -127,11 +129,11 @@ async function main() {
       } else {
         console.log('🏁 Scraping a single page is complete')
       }
-      server.close()
+      server.close(() => process.exit(0))
     })
     .on('error', (err) => {
       console.log('error listening to port ', port, err)
-      server.close()
+      server.close(() => process.exit(1))
     })
 }
 

src/ghes-releases/scripts/create-enterprise-issue.ts

@@ -0,0 +1,84 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+// Removing deprecated Liquid conditionals leaves behind extra blank lines.
+// The content team flags these every deprecation, and the MD012 linter rule
+// is off so nothing catches them automatically. This collapses any run of
+// two or more consecutive blank lines down to one, but only in the markdown
+// files the deprecation actually changed. Single blank lines are left alone:
+// removed Liquid can introduce one in a place where it doesn't belong, so a
+// human still reviews each removal site one at a time.
+
+function getChangedMarkdownFiles(): string[] {
+  const commands = [
+    'git diff --name-only HEAD',
+    'git diff --name-only --cached',
+    'git diff --name-only origin/main...HEAD',
+  ]
+  const files = new Set<string>()
+  for (const command of commands) {
+    let output = ''
+    try {
+      output = execSync(command, { encoding: 'utf8' })
+    } catch {
+      // origin/main may not be fetched locally; skip that source.
+      continue
+    }
+    for (const line of output.split('\n')) {
+      const file = line.trim()
+      if (!file) continue
+      if (!file.endsWith('.md')) continue
+      if (!file.startsWith('content/') && !file.startsWith('data/')) continue
+      if (fs.existsSync(file)) files.add(file)
+    }
+  }
+  return [...files].sort()
+}
+
+// Collapses any run of 2+ blank lines into a single blank line.
+function collapse(contents: string): string {
+  const lines = contents.split('\n')
+  const result: string[] = []
+  let blankRun = 0
+  for (const line of lines) {
+    if (line.trim() === '') {
+      blankRun += 1
+      if (blankRun <= 1) result.push('')
+    } else {
+      blankRun = 0
+      result.push(line)
+    }
+  }
+  return result.join('\n')
+}
+
+export function collapseBlankLines(options: { check?: boolean } = {}) {
+  const files = getChangedMarkdownFiles()
+  const offenders: string[] = []
+
+  for (const file of files) {
+    const contents = fs.readFileSync(file, 'utf8')
+    const collapsed = collapse(contents)
+    if (collapsed === contents) continue
+    offenders.push(file)
+    if (!options.check) {
+      fs.writeFileSync(file, collapsed)
+      console.log('Collapsed blank lines in: ', file)
+    }
+  }
+
+  if (options.check) {
+    if (offenders.length) {
+      console.error('Found 2+ consecutive blank lines in:')
+      for (const file of offenders) console.error(`  ${file}`)
+      console.error('Run `npm run deprecate-ghes -- collapse-blank-lines` to fix.')
+      process.exit(1)
+    }
+    console.log('No double blank lines found in changed markdown files.')
+    return
+  }
+
+  if (!offenders.length) {
+    console.log('No double blank lines found in changed markdown files.')
+  }
+}

src/ghes-releases/scripts/deprecate/archive-version.ts

@@ -46,7 +46,7 @@ mutation($repositoryId:ID!,$branch:String!,$requiredReviews:Int!) {
 }' -f repositoryId="$repositoryId" -f branch=main -F requiredReviews=1 --silent
 echo "--- Enable GitHub Pages, set source to main in root directory, and make the pages site public"
 gh api -X POST "/repos/github/docs-ghes-$version/pages" \
-  -f "source[branch]=main" -f "source[path]=/" -f "public=true" --silent
+  -f "source[branch]=main" -f "source[path]=/" -F "public=true" --silent
 echo "--- Update custom properties"
 gh api --method PATCH /repos/github/docs-ghes-$version/properties/values \
   -f "properties[][property_name]=ownership-name" \

src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts

@@ -3,31 +3,38 @@ import { execSync } from 'child_process'
 import { updateContentFiles } from '@/ghes-releases/scripts/deprecate/update-content'
 import { updateDataFiles } from '@/ghes-releases/scripts/deprecate/update-data'
 import { updateAutomatedConfigFiles } from '@/ghes-releases/scripts/deprecate/update-automated-pipelines'
-
-program.option('-f, --foo', 'enable some foo')
+import { collapseBlankLines } from '@/ghes-releases/scripts/deprecate/collapse-blank-lines'
 
 program
-  .description('Update deprecated versions frontmatter and remove deprecated content files.')
   .command('content')
+  .description('Update deprecated versions frontmatter and remove deprecated content files.')
   .action(updateContentFiles)
 
 program
+  .command('data')
   .description(
     'Update deprecated versions in data files, remove empty data files, and remove deleted reusables from content files.',
   )
-  .command('data')
   .action(updateDataFiles)
 
 program
+  .command('pipelines')
   .description(
     'Removes automated pipeline data files and updates the automated pipeline config files.',
   )
-  .command('pipelines')
   .action(updateAutomatedConfigFiles)
 
 program
+  .command('collapse-blank-lines')
+  .description(
+    'Collapse 2+ consecutive blank lines left by removed Liquid into one, in changed markdown files only. Pass --check to report without writing.',
+  )
+  .option('--check', 'Report files with double blank lines and exit non-zero instead of fixing.')
+  .action((options) => collapseBlankLines({ check: options.check }))
+
+program
+  .command('create-repo')
   .description('Create new `github/docs-ghes-<RELEASE>` repository.')
-  .command('repo')
   .option('-v, --version <version>', 'The GHES version to create the repo for.')
   .action((options) => {
     if (!options.version) {