Publish deprecation data

deprecations.js

@@ -0,0 +1,59 @@
+/*
+ * 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'],
+      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.`
+    }
+  ]
+}
+
+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(versionDeprecations)) {
+  for (const {selectors, message} of deps) {
+    for (const selector of selectors) {
+      selectorDeprecations.set(selector, {version, message})
+    }
+  }
+}
+
+function isSelectorDeprecated(selector, version = CURRENT_VERSION) {
+  const deprecation = selectorDeprecations.get(selector)
+  return deprecation ? semver.gte(deprecation.version, version) : false
+}
+
+module.exports = {versionDeprecations, selectorDeprecations, isSelectorDeprecated}

docs/content/tools/deprecations.md

@@ -0,0 +1,95 @@
+---
+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
+[JSON](#json).
+
+Deprecation messages strings may include Markdown so that they can be included
+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
+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 whose 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"
+```
+
+[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

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

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",
@@ -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",

script/dist

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
+/* eslint-disable no-console */
 const globby = require('globby')
 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 +69,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)
@@ -90,6 +91,14 @@ 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 = {
+    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))
 }