Merge branch 'main' into code-example-extravganza

Author: Kathy Korevec

contributing/development.md

@@ -32,6 +32,12 @@ As an alternative, you can simply use [GitHub Codespaces](https://github.com/fea
 
 In a matter of minutes, you will be ready to edit, preview and test your changes directly from the comfort of your browser.
 
+### Viewing a top-level table of contents
+
+While running the local server, you can visit [localhost:4000/dev-toc](http://localhost:4000/dev-toc) to view a top-level TOC of all the content in the site. This page is not available on https://docs.github.com. It was created for internal GitHub writers' use.
+
+At the `/dev-toc` path, you'll see a list of available versions. Click a version, and a list of products will appear. Note that the TOC content is versioned. If you are viewing `free-pro-team@latest` and you click the `Enterprise Admin` product, it will be empty, because there isn't any Admin content available on that version.
+
 ## Site structure
 
 This site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by [Jekyll](https://jekyllrb.com/). A few years after that it was migrated to [Nanoc](https://nanoc.ws/), another Ruby static site generator.

lib/enterprise-server-releases.js

@@ -7,10 +7,10 @@ const dates = require('../lib/enterprise-dates.json')
 const supported = [
   '2.22',
   '2.21',
-  '2.20',
-  '2.19'
+  '2.20'
 ]
 const deprecated = [
+  '2.19',
   '2.18',
   '2.17',
   '2.16',

lib/is-archived-version.js

@@ -0,0 +1,27 @@
+const patterns = require('../lib/patterns')
+const { deprecated } = require('../lib/enterprise-server-releases')
+
+module.exports = function isArchivedVersion (req) {
+  // if this is an assets path, use the referrer
+  // if this is a docs path, use the req.path
+  const pathToCheck = patterns.assetPaths.test(req.path)
+    ? req.get('referrer')
+    : req.path
+
+  // ignore paths that don't have an enterprise version number
+  if (!(patterns.getEnterpriseVersionNumber.test(pathToCheck) || patterns.getEnterpriseServerNumber.test(pathToCheck))) {
+    return {}
+  }
+
+  // extract enterprise version from path, e.g. 2.16
+  const requestedVersion = pathToCheck.includes('enterprise-server@')
+    ? pathToCheck.match(patterns.getEnterpriseServerNumber)[1]
+    : pathToCheck.match(patterns.getEnterpriseVersionNumber)[1]
+
+  // bail if the request version is not deprecated
+  if (!deprecated.includes(requestedVersion)) {
+    return {}
+  }
+
+  return { isArchived: true, requestedVersion }
+}

lib/redirects/static/developer-docs-routes-for-supported-versions.json

@@ -1,8 +1,6 @@
 const path = require('path')
-const versionSatisfiesRange = require('../lib/version-satisfies-range')
-const enterpriseServerReleases = require('../lib/enterprise-server-releases')
 const patterns = require('../lib/patterns')
-const firstVersionDeprecatedOnNewSite = '2.13'
+const isArchivedVersion = require('../lib/is-archived-version')
 const got = require('got')
 
 // This module handles requests for the CSS and JS assets for
@@ -12,33 +10,14 @@ const got = require('got')
 // See also ./archived-enterprise-versions.js for non-CSS/JS paths
 
 module.exports = async (req, res, next) => {
+  const { isArchived, requestedVersion } = isArchivedVersion(req)
+  if (!isArchived) return next()
+
   // Only match asset paths
   if (!patterns.assetPaths.test(req.path)) return next()
 
-  // Get the referrer, which may contain an enterprise version
-  const referrer = req.get('referrer')
-
-  // ignore paths that don't have an enterprise version number
-  if (!patterns.getEnterpriseVersionNumber.test(referrer)) return next()
-
-  // extract enterprise version from path, e.g. 2.16
-  const requestedVersion = referrer.match(patterns.getEnterpriseVersionNumber)[1]
-
-  // bail if the request version is not deprecated
-  if (!enterpriseServerReleases.deprecated.includes(requestedVersion)) return next()
-
-  // get /dist/index.js and /dist/index.css paths from enterprisified paths
   const assetPath = req.path.replace(`/enterprise/${requestedVersion}`, '')
-
-  // paths are slightly different depending on the enterprise version
-  let proxyPath
-  if (versionSatisfiesRange(requestedVersion, `>=${firstVersionDeprecatedOnNewSite}`)) {
-    // routing for >=2.13
-    proxyPath = path.join('/', requestedVersion, assetPath)
-  } else if (versionSatisfiesRange(requestedVersion, `<${firstVersionDeprecatedOnNewSite}`)) {
-    // routing for <2.13
-    proxyPath = path.join('/', requestedVersion, 'assets', assetPath)
-  }
+  const proxyPath = path.join('/', requestedVersion, assetPath)
 
   try {
     const r = await got(`https://github.github.com/help-docs-archived-enterprise-versions${proxyPath}`)

middleware/archived-enterprise-versions-assets.js

@@ -1,8 +1,9 @@
 const path = require('path')
 const slash = require('slash')
-const { latest, deprecated, firstVersionDeprecatedOnNewSite, lastVersionWithoutStubbedRedirectFiles } = require('../lib/enterprise-server-releases')
+const { latest, firstVersionDeprecatedOnNewSite, lastVersionWithoutStubbedRedirectFiles } = require('../lib/enterprise-server-releases')
 const patterns = require('../lib/patterns')
 const versionSatisfiesRange = require('../lib/version-satisfies-range')
+const isArchivedVersion = require('../lib/is-archived-version')
 const got = require('got')
 const findPage = require('../lib/find-page')
 
@@ -11,20 +12,12 @@ const findPage = require('../lib/find-page')
 // https://github.com/github/help-docs-archived-enterprise-versions
 
 module.exports = async (req, res, next) => {
+  const { isArchived, requestedVersion } = isArchivedVersion(req)
+  if (!isArchived) return next()
+
   // Skip asset paths
   if (patterns.assetPaths.test(req.path)) return next()
 
-  if (req.context.page) return next()
-
-  // ignore paths that don't have an enterprise version number
-  if (!patterns.getEnterpriseVersionNumber.test(req.path)) return next()
-
-  // extract enterprise version from path, e.g. 2.16
-  const requestedVersion = req.path.match(patterns.getEnterpriseVersionNumber)[1]
-
-  // bail if the request version is not deprecated
-  if (!deprecated.includes(requestedVersion)) return next()
-
   // redirect language-prefixed URLs like /en/enterprise/2.10 -> /enterprise/2.10
   // (this only applies to versions <2.13)
   if (req.path.startsWith('/en/') && versionSatisfiesRange(requestedVersion, `<${firstVersionDeprecatedOnNewSite}`)) {

middleware/archived-enterprise-versions.js

@@ -85,18 +85,13 @@ describe('deprecation banner', () => {
     expect($('.deprecation-banner b').text().endsWith('discontinued on .')).toBe(false)
   })
 
-  test('deprecation warning banner says "will be discontinued" when date is in future', async () => {
+  test('deprecation warning banner includes the right text depending on the date', async () => {
     const $ = await getDOM(`/en/enterprise/${enterpriseServerReleases.oldestSupported}`)
     const expectedString = enterpriseServerReleases.isOldestReleaseDeprecated
       ? 'was discontinued'
       : 'will be discontinued'
     expect($('.deprecation-banner b').text().includes(expectedString)).toBe(true)
   })
-
-  test('deprecation warning banner says "was discontinued" when date is in past', async () => {
-    const $ = await getDOM(`/en/enterprise/${enterpriseServerReleases.deprecated[0]}`)
-    expect($('.deprecation-banner b').text().includes('was discontinued')).toBe(true)
-  })
 })
 
 describe('does not render helpfulness prompt or contribution button', () => {
@@ -186,7 +181,7 @@ describe('JS and CSS assets', () => {
 
   it('returns the expected CSS file  ( <2.13 )', async () => {
     const result = await supertest(app)
-      .get('/stylesheets/application.css')
+      .get('/assets/stylesheets/application.css')
       .set('Referrer', '/en/enterprise/2.12')
 
     expect(result.statusCode).toBe(200)