Merge pull request #17310 from github/remove-fpt-helper

Add helper function that removes free-pro-team from URLs

Author: sarahs

content/README.md

@@ -24,6 +24,7 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
   - [Escaping single quotes](#escaping-single-quotes)
 - [Autogenerated mini TOCs](#autogenerated-mini-tocs)
 - [Versioning](#versioning)
+  - [Free-pro-team vs. GitHub.com versioning](#free-pro-team-vs.-git.colasdn.top-versioning)
 - [Filenames](#filenames)
 - [Whitespace control](#whitespace-control)
 - [Links and image paths](#links-and-image-paths)
@@ -213,6 +214,12 @@ A content file can have **two** types of versioning:
 * Liquid statements in content (**optional**)
     * Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files.
 
+### Free-pro-team vs. GitHub.com versioning
+
+As of early 2021, the `free-pro-team@latest` version is **only** supported in content files (in both frontmatter and Liquid versioning) and throughout the docs site backend. It is **not** user facing. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs. Users now select `GitHub.com` in the Article Versions dropdown instead of `Free, Pro, Team`.
+
+The convenience function allows us to continue supporting a consistent versioning structure under-the-hood while not displaying plan information to users that may be potentially confusing.
+
 ## Filenames
 
 When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter.
@@ -224,7 +231,7 @@ When using Liquid conditionals in lists or tables, you can use [whitespace contr
 Just add a hyphen on either the left, right, or both sides to indicate that there should be no newline on that side. For example, this statement removes a newline on the left side:
 
 ```
-{%- if page.version == 'dotcom' %}
+{%- if currentVersion == 'free-pro-team@latest' %}
 ```
 
 These characters are especially important in [index pages](#index-pages) comprised of list items.
@@ -238,9 +245,9 @@ For example, if you include the following link in a content file:
 ```
 /github/writing-on-github/creating-a-saved-reply
 ```
-When viewed on GitHub.com docs, the link gets rendered with the language code and version:
+When viewed on GitHub.com docs, the link gets rendered with the language code:
 ```
-/en/free-pro-team@latest/github/writing-on-github/creating-a-saved-reply
+/en/github/writing-on-github/creating-a-saved-reply
 ```
 and when viewed on GitHub Enterprise Server docs, the version is included as well:
 ```

contributing/development.md

@@ -48,7 +48,7 @@ For more detailed instructions, please see this [VS Code recipe](https://github.
 
 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.
+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 the `GitHub.com` version and you click the `Enterprise Admin` product, it will be empty, because there isn't any Admin content available on that version.
 
 ## Site structure
 

contributing/permalinks.md

@@ -4,18 +4,16 @@ Because the site is dynamic, it does not build HTML files for each different ver
 
 For example, an article that is available in currently supported versions will have permalink URLs like the following:
 
-* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
+* `/en/github/getting-started-with-github/set-up-git`
 * `/en/[email protected]/github/getting-started-with-github/set-up-git`
 * `/en/[email protected]/github/getting-started-with-github/set-up-git`
 * `/en/[email protected]/github/getting-started-with-github/set-up-git`
 * `/en/[email protected]/github/getting-started-with-github/set-up-git`
 
 An article that is not available in Enterprise will have just one permalink:
 
-* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
+* `/en/github/getting-started-with-github/set-up-git`
 
 **If you are a content contributor:** You don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article you can just use its relative location:
 
-* `/github/getting-started-with-github/set-up-git`
-
-*(Please note that using a hard-coded link or supported version will result in an error when your submitted PR is automatically tested)*
+* `/github/getting-started-with-github/set-up-git`

lib/all-products.js

@@ -7,6 +7,7 @@ const yaml = require('js-yaml')
 const contentDir = path.join(process.cwd(), 'content')
 const frontmatter = require('@github-docs/frontmatter')
 const getApplicableVersions = require('./get-applicable-versions')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 // the product order is determined by data/products.yml
 const productsFile = path.join(process.cwd(), 'data/products.yml')
@@ -46,7 +47,7 @@ sortedProductIds.forEach(productId => {
   const toc = slash(path.join(dir, 'index.md'))
   const { data } = frontmatter(fs.readFileSync(toc, 'utf8'))
   const applicableVersions = getApplicableVersions(data.versions, toc)
-  const href = slash(path.join('/', applicableVersions[0], productId))
+  const href = removeFPTFromPath(slash(path.join('/', applicableVersions[0], productId)))
 
   internalProducts[productId] = {
     id: productId,

lib/all-versions.js

@@ -7,9 +7,10 @@ const versionDelimiter = '@'
 const latestNonNumberedRelease = 'latest'
 
 const plans = [
-  {
+  { // free-pro-team is **not** a user-facing version and is stripped from URLs.
+    // See lib/remove-fpt-from-path.js for details.
     plan: 'free-pro-team',
-    planTitle: 'Free, Pro, and Team',
+    planTitle: 'GitHub.com',
     releases: [latestNonNumberedRelease],
     latestRelease: latestNonNumberedRelease,
     nonEnterpriseDefault: true, // permanent way to refer to this plan if the name changes

lib/get-link-data.js

@@ -1,6 +1,7 @@
 const path = require('path')
 const findPage = require('./find-page')
 const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 // rawLinks is an array of paths: [ '/foo' ]
 // we need to convert it to an array of localized objects: [ { href: '/en/foo', title: 'Foo', intro: 'Description here' } ]
@@ -12,7 +13,7 @@ module.exports = async (rawLinks, context, additionalProperties = []) => {
   for (const link of rawLinks) {
     const linkPath = link.href || link
     const version = context.currentVersion === 'homepage' ? nonEnterpriseDefaultVersion : context.currentVersion
-    const href = path.join('/', context.currentLanguage, version, linkPath)
+    const href = removeFPTFromPath(path.join('/', context.currentLanguage, version, linkPath))
 
     const linkedPage = findPage(href, context.pages, context.redirects)
     if (!linkedPage) continue

lib/path-utils.js

@@ -76,9 +76,13 @@ function getProductStringFromPath (href) {
 
   if (href === '/') return 'homepage'
 
-  return allProducts[href.split('/')[2]]
-    ? href.split('/')[2]
-    : href.split('/')[1]
+  const pathParts = href.split('/')
+
+  if (pathParts.includes('early-access')) return 'early-access'
+
+  return allProducts[pathParts[2]]
+    ? pathParts[2]
+    : pathParts[1]
 }
 
 // Return the corresponding object for the product segment in a path

lib/permalink.js

@@ -3,6 +3,8 @@ const path = require('path')
 const patterns = require('./patterns')
 const getApplicableVersions = require('./get-applicable-versions')
 const allVersions = require('./all-versions')
+const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 class Permalink {
   constructor (languageCode, pageVersion, relativePath, title) {
@@ -13,7 +15,7 @@ class Permalink {
 
     const permalinkSuffix = this.constructor.relativePathToSuffix(relativePath)
 
-    this.href = path.join('/', languageCode, pageVersion, permalinkSuffix)
+    this.href = removeFPTFromPath(path.join('/', languageCode, pageVersion, permalinkSuffix))
       .replace(patterns.trailingSlash, '$1')
 
     this.pageVersionTitle = allVersions[pageVersion].versionTitle
@@ -26,9 +28,12 @@ class Permalink {
     assert(languageCode, 'languageCode is required')
 
     const applicableVersions = getApplicableVersions(frontmatterVersions, path.join(languageCode, relativePath))
-    const permalinks = applicableVersions.map(pageVersion => {
-      return new Permalink(languageCode, pageVersion, relativePath, title)
-    })
+    const permalinks = applicableVersions
+      // skip the Dotcom homepage here because a special homepage permalink is added below
+      .filter(pageVersion => !(pageVersion === nonEnterpriseDefaultVersion && relativePath === 'index.md'))
+      .map(pageVersion => {
+        return new Permalink(languageCode, pageVersion, relativePath, title)
+      })
 
     // special permalink for homepage
     if (relativePath === 'index.md') {

lib/redirects/get-old-paths-from-permalink.js

@@ -1,5 +1,5 @@
-const { latest, lastReleaseWithLegacyFormat } = require('../enterprise-server-releases')
-const { getPathWithoutLanguage, getPathWithLanguage } = require('../path-utils')
+const { latest, deprecated, lastReleaseWithLegacyFormat } = require('../enterprise-server-releases')
+const { getPathWithoutLanguage, getPathWithLanguage, getVersionStringFromPath } = require('../path-utils')
 const patterns = require('../patterns')
 const versionSatisfiesRange = require('../version-satisfies-range')
 const currentlySupportedVersions = Object.keys(require('../all-versions'))
@@ -11,6 +11,15 @@ const nonEnterpriseDefaultVersion = require('../non-enterprise-default-version')
 module.exports = function getOldPathsFromPath (currentPath, languageCode, currentVersion) {
   const oldPaths = new Set()
 
+  const versionFromPath = getVersionStringFromPath(currentPath)
+
+  // This only applies to Dotcom paths, so no need to determine whether the version is deprecated
+  // create old path /free-pro-team@latest/github from new path /github (or from a frontmatter `redirect_from` path like /articles)
+  if (versionFromPath === 'homepage' || !(currentlySupportedVersions.includes(versionFromPath) || deprecated.includes(versionFromPath)) || (versionFromPath === nonEnterpriseDefaultVersion && !currentPath.includes(nonEnterpriseDefaultVersion))) {
+    oldPaths.add(currentPath
+      .replace(`/${languageCode}`, `/${languageCode}/${nonEnterpriseDefaultVersion}`))
+  }
+
   // ------ BEGIN LEGACY VERSION FORMAT REPLACEMENTS ------//
   // These remain relevant to handle legacy-formatted frontmatter redirects
   // and archived versions paths.
@@ -57,14 +66,6 @@ module.exports = function getOldPathsFromPath (currentPath, languageCode, curren
   // ------ BEGIN MODERN VERSION FORMAT REPLACEMENTS ------//
   if (currentlySupportedVersions.includes(currentVersion) || versionSatisfiesRange(currentVersion, `>${lastReleaseWithLegacyFormat}`)) {
     (new Set(oldPaths)).forEach(oldPath => {
-      // create old path /github from new path /free-pro-team@latest/github
-      oldPaths.add(oldPath
-        .replace(`/${nonEnterpriseDefaultVersion}`, ''))
-
-      // create old path /free-pro-team/github from new path /free-pro-team@latest/github
-      oldPaths.add(oldPath
-        .replace('@latest', ''))
-
       // create old path /enterprise/<version> from new path /enterprise-server@<version>
       oldPaths.add(oldPath
         .replace(/\/enterprise-server@(\d)/, '/enterprise/$1'))

lib/redirects/permalinks.js

@@ -4,6 +4,7 @@ const supportedVersions = new Set(Object.keys(require('../all-versions')))
 const getOldPathsFromPermalink = require('./get-old-paths-from-permalink')
 const { getVersionStringFromPath } = require('../path-utils')
 const { getNewVersionedPath } = require('../old-versions-utils')
+const removeFPTFromPath = require('../remove-fpt-from-path')
 
 module.exports = function generateRedirectsForPermalinks (permalinks, redirectFrontmatter) {
   // account for Array or String frontmatter entries
@@ -37,7 +38,7 @@ module.exports = function generateRedirectsForPermalinks (permalinks, redirectFr
       // get the old path for the current permalink version
       let versionedFrontmatterOldPath = path.join('/', permalink.languageCode, getNewVersionedPath(frontmatterOldPath))
       const versionFromPath = getVersionStringFromPath(versionedFrontmatterOldPath)
-      versionedFrontmatterOldPath = versionedFrontmatterOldPath.replace(versionFromPath, permalink.pageVersion)
+      versionedFrontmatterOldPath = removeFPTFromPath(versionedFrontmatterOldPath.replace(versionFromPath, permalink.pageVersion))
 
       // add it to the redirects object
       redirects[versionedFrontmatterOldPath] = permalink.href