From 0cff29689783d6a0aa4c52ad547521f458a3ebd6 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 11:13:19 -0700
Subject: [PATCH 01/13] bump semver

---
 package-lock.json | 6 +++---
 package.json      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 58f5fd3c..df27f46e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14170,9 +14170,9 @@
       "optional": true
     },
     "semver": {
-      "version": "5.7.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.0.tgz",
-      "integrity": "sha512-Ya52jSX2u7QKghxeoFGpLwCtGlt7j0oY9DYb5apt9nPlJ42ID+ulTXESnt/qAQcoSERyZ5sl3LDIOw0nAn/5DA==",
+      "version": "5.7.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz",
+      "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==",
       "dev": true
     },
     "send": {
diff --git a/package.json b/package.json
index f0b37d8d..30c30986 100644
--- a/package.json
+++ b/package.json
@@ -79,7 +79,7 @@
     "prop-types": "^15.6.2",
     "raw-loader": "0.5.1",
     "refractor": "^2.6.2",
-    "semver": "^5.3.0",
+    "semver": "5.7.1",
     "style-loader": "^0.18.2",
     "styled-components": "4.1.2",
     "stylelint": "9.10.1",

From 81ae8d978849b99d9b99ee72fc8f13d2b1c58b38 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 11:13:45 -0700
Subject: [PATCH 02/13] add deprecations/index.js; write dist/deprecations.json

---
 deprecations/index.js | 44 +++++++++++++++++++++++++++++++++++++++++++
 script/dist           |  9 +++++++--
 2 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 deprecations/index.js

diff --git a/deprecations/index.js b/deprecations/index.js
new file mode 100644
index 00000000..ff1a2793
--- /dev/null
+++ b/deprecations/index.js
@@ -0,0 +1,44 @@
+const {version: CURRENT_VERSION} = require('../package.json')
+const semver = require('semver')
+
+const deprecationsByVersion = {
+  '13.0.0': [
+    {
+      selectors: ['.btn-purple'],
+      message: `Please don't make purple buttons.`
+    },
+    {
+      selectors: ['.text-pending'],
+      message: `Please use the "text-yellow" class instead of "text-pending".`
+    },
+    {
+      selectors: ['.bg-pending'],
+      message: `Please use the "bg-yellow-dark" class instead of "bg-pending".`
+    },
+    {
+      selectors: ['.columns', '.column', '.one-third', '.two-thirds', '.one-fourth', '.one-half', '.three-fourths', '.one-fifth', '.four-fifths'],
+      message: `Please use [grid classes](https://primer.style/css/objects/grid).`
+    },
+    {
+      selectors: ['.centered'],
+      message: `You can use the "mx-auto" class to center any element.`
+    }
+  ]
+}
+
+// map selectors to the version and message of their deprecation
+const selectorDeprecations = new Map()
+for (const [version, deps] of Object.entries(deprecationsByVersion)) {
+  for (const {selectors, message} of deps) {
+    for (const selector of selectors) {
+      selectorDeprecations.set(selector, {version, message})
+    }
+  }
+}
+
+function isSelectorDeprecated(selector, version = CURRENT_VERSION) {
+  const dep = selectorDeprecations.get(selector)
+  return dep ? semver.gte(dep.version, version) : false
+}
+
+module.exports = {deprecationsByVersion, selectorDeprecations, isSelectorDeprecated}
diff --git a/script/dist b/script/dist
index 508966e2..7dbb0c2a 100755
--- a/script/dist
+++ b/script/dist
@@ -4,8 +4,7 @@ const cssstats = require('cssstats')
 const postcss = require('postcss')
 const loadConfig = require('postcss-load-config')
 const {remove, mkdirp, readFile, writeFile} = require('fs-extra')
-const {dirname, basename, join} = require('path')
-const {promisify} = require('util')
+const {dirname, join} = require('path')
 
 const inDir = 'src'
 const outDir = 'dist'
@@ -69,6 +68,7 @@ remove(outDir)
         const meta = {bundles}
         return writeFile(join(outDir, 'meta.json'), JSON.stringify(meta, null, 2), encoding)
       })
+      .then(writeDeprecationData)
   })
   .catch(error => {
     console.error(error)
@@ -93,3 +93,8 @@ function getPathName(path) {
 function unique(d, i, list) {
   return list.indexOf(d) === i
 }
+
+function writeDeprecationData() {
+  const {deprecationsByVersion} = require('../deprecations')
+  return writeFile(join(outDir, 'deprecations.json'), JSON.stringify(deprecationsByVersion, null, 2))
+}

From 5ab29b5a6783c0357d86b50bda493504925870d1 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 11:55:10 -0700
Subject: [PATCH 03/13] better deprecation data key naming

---
 deprecations/index.js | 17 +++++++++++------
 script/dist           | 11 +++++++++--
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/deprecations/index.js b/deprecations/index.js
index ff1a2793..5541c838 100644
--- a/deprecations/index.js
+++ b/deprecations/index.js
@@ -1,7 +1,9 @@
-const {version: CURRENT_VERSION} = require('../package.json')
-const semver = require('semver')
-
-const deprecationsByVersion = {
+/*
+ * This object's keys are (semver) version numbers, and the
+ * values are arrays of objects each with a "selectors"
+ * array and a "message" string.
+ */
+const versionDeprecations = {
   '13.0.0': [
     {
       selectors: ['.btn-purple'],
@@ -26,9 +28,12 @@ const deprecationsByVersion = {
   ]
 }
 
+const {version: CURRENT_VERSION} = require('../package.json')
+const semver = require('semver')
+
 // map selectors to the version and message of their deprecation
 const selectorDeprecations = new Map()
-for (const [version, deps] of Object.entries(deprecationsByVersion)) {
+for (const [version, deps] of Object.entries(versionDeprecations)) {
   for (const {selectors, message} of deps) {
     for (const selector of selectors) {
       selectorDeprecations.set(selector, {version, message})
@@ -41,4 +46,4 @@ function isSelectorDeprecated(selector, version = CURRENT_VERSION) {
   return dep ? semver.gte(dep.version, version) : false
 }
 
-module.exports = {deprecationsByVersion, selectorDeprecations, isSelectorDeprecated}
+module.exports = {versionDeprecations, selectorDeprecations, isSelectorDeprecated}
diff --git a/script/dist b/script/dist
index 7dbb0c2a..03c5e6fa 100755
--- a/script/dist
+++ b/script/dist
@@ -95,6 +95,13 @@ function unique(d, i, list) {
 }
 
 function writeDeprecationData() {
-  const {deprecationsByVersion} = require('../deprecations')
-  return writeFile(join(outDir, 'deprecations.json'), JSON.stringify(deprecationsByVersion, null, 2))
+  const {versionDeprecations, selectorDeprecations} = require('../deprecations')
+  const data = {
+    versions: versionDeprecations,
+    selectors: Array.from(selectorDeprecations.entries()).reduce((obj, [selector, deprecation]) => {
+      obj[selector] = deprecation
+      return obj
+    }, {})
+  }
+  return writeFile(join(outDir, 'deprecations.json'), JSON.stringify(data, null, 2))
 }

From c5ada08116eb7f128e7cffc95f0ed0e5a8b53461 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 11:55:25 -0700
Subject: [PATCH 04/13] add deprecations page, nav item

---
 docs/content/tools/deprecations.md            | 89 +++++++++++++++++++
 .../src/@primer/gatsby-theme-doctocat/nav.yml |  2 +
 2 files changed, 91 insertions(+)
 create mode 100644 docs/content/tools/deprecations.md

diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md
new file mode 100644
index 00000000..c061b3d0
--- /dev/null
+++ b/docs/content/tools/deprecations.md
@@ -0,0 +1,89 @@
+## Deprecation data
+
+As of version 12.7.0, we publish CSS selector deprecation data with
+`@primer/css`. You can access the data via the [Node API](#node) or as
+[JSON](#json).
+
+Deprecation messages strings may include Markdown so that they can be included
+in the [changelog](https://github.com/primer/css/tree/master/CHANGELOG.md).
+
+**Keep in mind that this data includes both active and _planned_
+deprecations.** You can determine whether a CSS selector is deprecated for the
+version of `@primer/css` you've installed via the [Node API](#node), or by
+comparing the version of a selector deprecation with the installed version in
+your own environment.
+
+### JSON
+
+The JSON data is available in the unpacked node module's `dist/deprecations.json`, and is an object with the following structure:
+
+* `versions` is an object whos keys are version numbers (e.g. `13.0.0`) and values are deprecation messages: objects with a `selectors` array and a `message`:
+
+    ```json
+    {
+      "versions": {
+        "13.0.0": [
+          {
+            "selectors": [".btn-purple"],
+            "message": "Please don't make purple buttons."
+          }
+        ]
+      }
+    }
+    ```
+
+* `selectors` is an object mapping CSS selectors (e.g. `.btn-purple`) to the version in which they are _or will be_ deprecated:
+
+    ```json
+    {
+      "selectors": {
+        ".btn-purple": {
+          "version": "13.0.0",
+          "message": "Please don't make purple buttons."
+        }
+      }
+    }
+    ```
+
+### Node
+
+The Node API for selector deprecations is available at
+`@primer/css/deprecations`.
+
+**Note:** Because we have chosen not to bundle any runtime dependencies with
+`@primer/css`, you will need to install the [semver] dependency yourself:
+
+```shell
+npm install semver
+```
+
+#### `versionDeprecations`
+This is the object literal form of the [JSON data's](#json) `versions` object.
+For instance, to list all of the deprecations:
+
+```js
+const {versionDeprecations} = require('@primer/css/deprecations')
+for (const [version, deprecations] of Object.entries(versionDeprecations)) {
+  console.log(`${version}: ${deprecations.length} deprecations`)
+}
+```
+
+#### `selectorDeprecations`
+This is a [Map] object with keys for each CSS selector mapped to the deprecation info:
+
+```js
+const {selectorDeprecations} = require('@primer/css/deprecations')
+console.log(`Purple buttons are going away? ${selectorDeprecations.has('.btn-purple')}`)
+// "Purple buttons are going away? true"
+```
+
+### `isSelectorDeprecated(selector[, version])`
+Returns `true` if the CSS `selector` will have been deprecated (removed) _by_ the specified [semver] version.
+
+```js
+const {isSelectorDeprecated} = require('@primer/css/deprecations')
+console.log(`Purple buttons are bad? ${isSelectorDeprecated('.btn-purple')}`)
+// "Purple buttons are bad? true"
+console.log(`Primary buttons are bad? ${isSelectorDeprecated('.btn-primary')}`)
+// "Primary buttons are bad? false"
+```
diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
index 329bf511..23aa8d5b 100644
--- a/docs/src/@primer/gatsby-theme-doctocat/nav.yml
+++ b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -122,6 +122,8 @@
   children:
     - title: Atom packages
       url: /tools/atom-packages
+    - title: Deprecation data
+      url: /tools/deprecations
     - title: Docset
       url: /tools/docset
     - title: Linting

From 034f1e01ee74d7280f17868ed95588604876055d Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:03:17 -0700
Subject: [PATCH 05/13] fix semver links

---
 docs/content/tools/deprecations.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md
index c061b3d0..3c7b7ad9 100644
--- a/docs/content/tools/deprecations.md
+++ b/docs/content/tools/deprecations.md
@@ -87,3 +87,5 @@ console.log(`Purple buttons are bad? ${isSelectorDeprecated('.btn-purple')}`)
 console.log(`Primary buttons are bad? ${isSelectorDeprecated('.btn-primary')}`)
 // "Primary buttons are bad? false"
 ```
+
+[semver]: https://npm.im/semver

From 2484b3327ef35b8a09d1f057687a46b56c45ff1d Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:20:46 -0700
Subject: [PATCH 06/13] add title front matter

---
 docs/content/tools/deprecations.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md
index 3c7b7ad9..aef6d7f7 100644
--- a/docs/content/tools/deprecations.md
+++ b/docs/content/tools/deprecations.md
@@ -1,4 +1,6 @@
-## Deprecation data
+---
+title: Deprecation data
+---
 
 As of version 12.7.0, we publish CSS selector deprecation data with
 `@primer/css`. You can access the data via the [Node API](#node) or as
@@ -13,7 +15,7 @@ version of `@primer/css` you've installed via the [Node API](#node), or by
 comparing the version of a selector deprecation with the installed version in
 your own environment.
 
-### JSON
+## JSON
 
 The JSON data is available in the unpacked node module's `dist/deprecations.json`, and is an object with the following structure:
 
@@ -45,7 +47,7 @@ The JSON data is available in the unpacked node module's `dist/deprecations.json
     }
     ```
 
-### Node
+## Node
 
 The Node API for selector deprecations is available at
 `@primer/css/deprecations`.
@@ -57,7 +59,7 @@ The Node API for selector deprecations is available at
 npm install semver
 ```
 
-#### `versionDeprecations`
+### `versionDeprecations`
 This is the object literal form of the [JSON data's](#json) `versions` object.
 For instance, to list all of the deprecations:
 
@@ -68,7 +70,7 @@ for (const [version, deprecations] of Object.entries(versionDeprecations)) {
 }
 ```
 
-#### `selectorDeprecations`
+### `selectorDeprecations`
 This is a [Map] object with keys for each CSS selector mapped to the deprecation info:
 
 ```js

From 988bc9f3063ba22124c7a9df158ac3b5bbe72d90 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:27:05 -0700
Subject: [PATCH 07/13] =?UTF-8?q?"whos"=20=E2=86=92=20"whose"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Zeke Sikelianos <zeke@sikelianos.com>
---
 docs/content/tools/deprecations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md
index aef6d7f7..2b2bf63a 100644
--- a/docs/content/tools/deprecations.md
+++ b/docs/content/tools/deprecations.md
@@ -19,7 +19,7 @@ your own environment.
 
 The JSON data is available in the unpacked node module's `dist/deprecations.json`, and is an object with the following structure:
 
-* `versions` is an object whos keys are version numbers (e.g. `13.0.0`) and values are deprecation messages: objects with a `selectors` array and a `message`:
+* `versions` is an object whose keys are version numbers (e.g. `13.0.0`) and values are deprecation messages: objects with a `selectors` array and a `message`:
 
     ```json
     {

From bfc2e2e45953d385109f2e673abf39af216d582c Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:30:11 -0700
Subject: [PATCH 08/13] rename deprecations/index.js -> deprecations.js

---
 deprecations/index.js => deprecations.js | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename deprecations/index.js => deprecations.js (100%)

diff --git a/deprecations/index.js b/deprecations.js
similarity index 100%
rename from deprecations/index.js
rename to deprecations.js

From c85b18fdd298f2e8c6a2cfb170591e76257f41fd Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:32:03 -0700
Subject: [PATCH 09/13] add [Map] link, move [changelog] href to footer

---
 docs/content/tools/deprecations.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md
index 2b2bf63a..1f28a910 100644
--- a/docs/content/tools/deprecations.md
+++ b/docs/content/tools/deprecations.md
@@ -7,7 +7,7 @@ As of version 12.7.0, we publish CSS selector deprecation data with
 [JSON](#json).
 
 Deprecation messages strings may include Markdown so that they can be included
-in the [changelog](https://github.com/primer/css/tree/master/CHANGELOG.md).
+in the [changelog].
 
 **Keep in mind that this data includes both active and _planned_
 deprecations.** You can determine whether a CSS selector is deprecated for the
@@ -91,3 +91,5 @@ console.log(`Primary buttons are bad? ${isSelectorDeprecated('.btn-primary')}`)
 ```
 
 [semver]: https://npm.im/semver
+[changelog]: https://github.com/primer/css/tree/master/CHANGELOG.md
+[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map

From eadec4c6af634c492adf0a4580bfc084c621ab64 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:33:11 -0700
Subject: [PATCH 10/13] lint, "dep" -> "deprecation"

---
 deprecations.js | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/deprecations.js b/deprecations.js
index 5541c838..1bc12fda 100644
--- a/deprecations.js
+++ b/deprecations.js
@@ -18,7 +18,17 @@ const versionDeprecations = {
       message: `Please use the "bg-yellow-dark" class instead of "bg-pending".`
     },
     {
-      selectors: ['.columns', '.column', '.one-third', '.two-thirds', '.one-fourth', '.one-half', '.three-fourths', '.one-fifth', '.four-fifths'],
+      selectors: [
+        '.columns',
+        '.column',
+        '.one-third',
+        '.two-thirds',
+        '.one-fourth',
+        '.one-half',
+        '.three-fourths',
+        '.one-fifth',
+        '.four-fifths'
+      ],
       message: `Please use [grid classes](https://primer.style/css/objects/grid).`
     },
     {
@@ -42,8 +52,8 @@ for (const [version, deps] of Object.entries(versionDeprecations)) {
 }
 
 function isSelectorDeprecated(selector, version = CURRENT_VERSION) {
-  const dep = selectorDeprecations.get(selector)
-  return dep ? semver.gte(dep.version, version) : false
+  const deprecation = selectorDeprecations.get(selector)
+  return deprecation ? semver.gte(deprecation.version, version) : false
 }
 
 module.exports = {versionDeprecations, selectorDeprecations, isSelectorDeprecated}

From 5c43eea7dd947fc4269813a86464e910442d51f2 Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:37:14 -0700
Subject: [PATCH 11/13] fix path to package.json

---
 deprecations.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/deprecations.js b/deprecations.js
index 1bc12fda..c6f84a2d 100644
--- a/deprecations.js
+++ b/deprecations.js
@@ -38,7 +38,7 @@ const versionDeprecations = {
   ]
 }
 
-const {version: CURRENT_VERSION} = require('../package.json')
+const {version: CURRENT_VERSION} = require('./package.json')
 const semver = require('semver')
 
 // map selectors to the version and message of their deprecation

From 3077a09705cd79d42c9663c42c4032c2045457bb Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:37:55 -0700
Subject: [PATCH 12/13] lint deprecations.js

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 30c30986..2a3266d4 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,7 @@
     "check-links": "script/check-links http://localhost:3000/css -v",
     "lint": "npm-run-all -s lint-css lint-js",
     "lint-css": "stylelint --quiet --syntax scss src/**/*.scss",
-    "lint-js": "eslint lib docs .storybook",
+    "lint-js": "eslint script lib docs deprecations.js .storybook",
     "now-build": "npm run dist && next build",
     "now-start": "next start",
     "now-test": "npm-run-all -s now-build now-start",

From bdd1208fc0e0ff81366f83c20d3ef19afdcb45ed Mon Sep 17 00:00:00 2001
From: Shawn Allen <shawn.allen@github.com>
Date: Thu, 5 Sep 2019 12:38:06 -0700
Subject: [PATCH 13/13] lint script/dist

---
 script/dist | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/script/dist b/script/dist
index 03c5e6fa..8a4bd14c 100755
--- a/script/dist
+++ b/script/dist
@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* eslint-disable no-console */
 const globby = require('globby')
 const cssstats = require('cssstats')
 const postcss = require('postcss')
@@ -90,10 +91,6 @@ function getPathName(path) {
   return path.replace(/\//g, '-')
 }
 
-function unique(d, i, list) {
-  return list.indexOf(d) === i
-}
-
 function writeDeprecationData() {
   const {versionDeprecations, selectorDeprecations} = require('../deprecations')
   const data = {