Merge pull request #625 from primer/release-10.10.3

Release 10.10.3

.gitignore

@@ -6,4 +6,5 @@
 .sass-cache
 _site
 build
+primer-version.txt
 node_modules

.travis.yml

@@ -13,28 +13,19 @@ script:
   - npm test
   - script/check-versions
 
-after_success:
+before_deploy:
   # this will short-circuit the publish step if it fails to interpolate $NPM_API_KEY
   - npm config set "//registry.npmjs.org/:_authToken=\${NPM_API_KEY}"
   # copy the CHANGELOG.md primer for publishing
   - cp CHANGELOG.md modules/primer
-  - script/after_success
 
 deploy:
-  # publish release candidates on release branches
+  # publish canary releases on all branches *except* master and release-*
   - provider: script
-    script: script/release-candidate
+    script: script/deploy --yes
     skip_cleanup: true
     on:
-      branch: release*
-      tags: false
-
-  # publish "final" releases on master
-  - provider: script
-    script: script/release
-    skip_cleanup: true
-    on:
-      branch: master
+      all_branches: true
       tags: false
 
 notifications:

CHANGELOG.md

@@ -1,3 +1,16 @@
+# 10.10.3
+#### :memo: Documentation
+* [#632](https://github.com/primer/primer/pull/632) Happy new year! ([@shawnbot](https://github.com/shawnbot))
+* [#626](https://github.com/primer/primer/pull/626) Branch deployment, docs for the docs. ([@shawnbot](https://github.com/shawnbot))
+* [#616](https://github.com/primer/primer/pull/616) Start up the docs directory. ([@shawnbot](https://github.com/shawnbot))
+
+#### :house: Internal
+* [#631](https://github.com/primer/primer/pull/631) Docs release fixes. ([@shawnbot](https://github.com/shawnbot))
+
+#### Committers: 2
+- Emily Brick ([emilybrick](https://github.com/emilybrick))
+- Shawn Allen ([shawnbot](https://github.com/shawnbot))
+
 # 10.10.2
 
 #### :memo: Documentation

docs/.eslintrc.json

@@ -0,0 +1,15 @@
+{
+  "extends": [
+    "plugin:github/es6",
+    "plugin:github/react",
+    "plugin:jsx-a11y/recommended"
+  ],
+  "settings": {
+    "react": {
+      "version": "^16.6"
+    }
+  },
+  "rules": {
+    "import/no-namespace": 0
+  }
+}

docs/.gitignore

@@ -0,0 +1,3 @@
+.next/
+after.txt
+static/primer.css

docs/README.md

@@ -0,0 +1,58 @@
+# Primer CSS docs site
+This directory hosts a [Next] site that pulls in Primer CSS documentation from the [modules directory](../modules).
+
+## Running the site
+First, make sure that you've bootstrapped the monorepo from the top-level directory. The `fresh` run-script will ensure that all `node_modules` or `package-lock.json` files are removed first:
+
+```
+# in the repo root
+npm run fresh
+```
+
+Then, navigate to this directory (`cd docs`) and run:
+
+```sh
+# in the docs directory
+npm run dev
+```
+
+This should start up the Next dev server and a background task that will keep the `pages` directory up-to-date whenever you change the source files in `modules/primer*`.
+
+## Syncing the docs
+If, for whatever reason, the dev server isn't syncing files, you have two choices:
+
+1. Stop the server (`ctrl-C`) and restart it (`npm run dev`), which will re-sync the files and clear Next's cache.
+2. Run [script/sync](./script/sync) manually:
+
+    ```sh
+    # in the docs directory
+    script/sync
+    ```
+
+    **If you find yourself needing to do this often, please [file an issue](/primer/primer/issues/new) and tag `@shawnbot`**. :bow:
+
+## The pages directory
+The [pages directory](./pages/) contains all of the files that map to URLs on the site. Because we plan to host the site at `primer.style/css` (and because of the way that Now's path aliasing feature works), we nest all of our documentation under the additional [css directory](./pages/css).
+
+The sync task maintains a listing of files that it's copied from the modules directory in `pages/css/.gitignore`, which ensures that none of these files are checked into git.
+
+If you find yourself editing a file, 
+
+## Sync internals
+
+We use [Metalsmith] to sync the source docs to the `pages` directory and transform them in the following ways:
+
+1. We filter the list of files to only Markdown documents and `package.json` files
+1. Many package `README.md`s wrap the actual documentation content in `<!-- %docs -->` HTML comments that usually include YAML frontmatter. In these instances, we extract the content that portion and reformat the frontmatter.
+1. We filter out any Markdown files that _don't_ include a `path` frontmatter key, and rename the destination file to match the `path` (e.g. `path: foo/bar` writes to `pages/css/foo/bar.md`).
+1. We set the `source` frontmatter key to a fully-qualified `github.com` URL for the source file so that we can link directly to it.
+1. A limited list of fields for all packages is extracted into a single file (`pages/css/packages.json`), which serves as a light-weight dependency graph.
+1. We read [the changelog](../CHANGELOG.md) and write it to `whats-new/changelog.md` with some additional frontmatter.
+1. We read the list of files from `pages/css/.gitignore` and delete them from the filesystem, then write the new list of paths so that they aren't committed to git.
+
+All of the logic for syncing the source docs (and transforming them in transit) is controlled in [`lib/sync.js`](./lib/sync.js), and each "step" in the transformation (as well as the watching) is implemented as a Metalsmith plugin.
+
+**Why [Metalsmith]?** We're glad you asked! `@shawnbot` likes the simplicity of Metalsmith's core and how easy it is to write powerful plugins.
+
+[Metalsmith]: https://metalsmith.io/
+[Next]: https://github.com/zeit/next.js

docs/before.txt

@@ -0,0 +1,78 @@
+./components/alerts.md
+./components/avatars.md
+./components/blankslate.md
+./components/box-overlay.md
+./components/box.md
+./components/boxed-groups.md
+./components/branch-name.md
+./components/breadcrumb.md
+./components/buttons.md
+./components/dropdown.md
+./components/flash-banner.md
+./components/forms.md
+./components/index.md
+./components/labels.md
+./components/markdown.md
+./components/marketing-buttons.md
+./components/navigation.md
+./components/octicons.md
+./components/page-headers.md
+./components/page-sections.md
+./components/pagehead.md
+./components/pagination.md
+./components/popover.md
+./components/progress.md
+./components/select-menu.md
+./components/subhead.md
+./components/tables.md
+./components/tooltips.md
+./components/truncate.md
+./getting_started/contributing.md
+./getting_started/index.md
+./objects/grid.md
+./objects/index.md
+./objects/layout.md
+./objects/table-object.md
+./packages/primer-core.md
+./packages/primer-marketing.md
+./packages/primer-product.md
+./packages/primer.md
+./principles/HTML.md
+./principles/SCSS.md
+./principles/accessibility.md
+./principles/index.md
+./support/breakpoints.md
+./support/color-system.md
+./support/index.md
+./support/marketing-variables.md
+./support/spacing.md
+./support/typography.md
+./tools/atom-packages.md
+./tools/docset.md
+./tools/index.md
+./tools/linting.md
+./tools/local-primer.md
+./tools/prototyping.md
+./tools/sketch-templates.md
+./tools/testing.md
+./utilities/animations.md
+./utilities/borders.md
+./utilities/box-shadow.md
+./utilities/colors.md
+./utilities/details.md
+./utilities/flexbox.md
+./utilities/index.md
+./utilities/layout.md
+./utilities/margin.md
+./utilities/marketing-borders.md
+./utilities/marketing-filters.md
+./utilities/marketing-layout.md
+./utilities/marketing-margin.md
+./utilities/marketing-padding.md
+./utilities/marketing-type.md
+./utilities/padding.md
+./utilities/typography.md
+./whats_new/changelog.md
+./whats_new/changelog/archived_changelog.md
+./whats_new/index.md
+./whats_new/status-key.md

docs/lib/add-package-meta.js

@@ -0,0 +1,44 @@
+const {existsSync} = require('fs')
+const {dirname, join, resolve} = require('path')
+
+const cache = {}
+
+module.exports = function addPackageMeta(options = {}) {
+  const {fields, namespace = 'data', log = noop} = options
+  return (files, metal, done) => {
+    const root = metal.source()
+    for (const [path, file] of Object.entries(files)) {
+      const pkg = getPackageRelativeTo(path, root)
+      if (pkg) {
+        file[namespace].package = fields ? pluck(pkg, fields) : pkg
+      } else {
+        log('no package.json found relative to', path)
+      }
+    }
+    done()
+  }
+}
+
+function getPackageRelativeTo(file, root) {
+  let dir = join(root, dirname(file))
+  if (dir in cache) {
+    return cache[dir]
+  }
+  while (dir !== root) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      return (cache[dir] = require(pkgPath))
+    }
+    dir = resolve(dir, '..')
+  }
+  return false
+}
+
+function pluck(data, fields) {
+  return fields.reduce((out, field) => {
+    out[field] = data[field]
+    return out
+  }, {})
+}
+
+function noop() {}

docs/lib/add-source.js

@@ -0,0 +1,16 @@
+const each = require('./each')
+
+module.exports = function addSource(options = {}) {
+  const {namespace = 'data'} = options
+  for (const key of ['branch', 'repo']) {
+    if (!options[key]) {
+      throw new Error(`addSource() plugin requires options.${key} (got ${JSON.stringify(options[key])})`)
+    }
+  }
+  const {branch, repo} = options
+  return each((file, source) => {
+    if (file[namespace]) {
+      file[namespace].source = `https://github.com/${repo}/tree/${branch}/modules/${source}`
+    }
+  })
+}

docs/lib/changelog.js

@@ -0,0 +1,17 @@
+const {readFileSync} = require('fs')
+
+module.exports = function addChangelog(sourcePath, destPath, transform = noop) {
+  return (files, metal, done) => {
+    const path = metal.path(metal.source(), sourcePath)
+    const file = {
+      contents: readFileSync(path),
+      path: destPath
+    }
+    transform(file)
+    files[destPath] = file
+    done()
+  }
+}
+
+function noop() {
+}

docs/lib/config.js

@@ -0,0 +1,69 @@
+/* eslint-disable no-console */
+const sync = require('./sync')
+const {CI, NODE_ENV, NOW_URL} = process.env
+
+const PRIMER_SCSS = 'primer/index.scss$'
+const PRIMER_STATIC_CSS = require.resolve('primer/build/build.css')
+
+module.exports = (nextConfig = {}) => {
+  const {assetPrefix = NOW_URL || ''} = nextConfig
+
+  let configured = false
+
+  return Object.assign({}, nextConfig, {
+    assetPrefix,
+    pageExtensions: ['js', 'jsx', 'md', 'mdx'],
+
+    publicRuntimeConfig: Object.assign({
+      assetPrefix,
+      production: NODE_ENV === 'production'
+    }, nextConfig.publicRuntimeConfig),
+
+    webpack(config, options) {
+      if (!options.defaultLoaders) {
+        throw new Error(
+          'This plugin is not compatible with Next.js versions below 5.0.0 https://err.sh/next-plugins/upgrade'
+        )
+      }
+
+      const {dev} = options
+
+      // only attempt to sync locally and in CI
+      if (dev && !configured) {
+        sync({watch: !CI})
+      }
+
+      config.module.rules.push({
+        test: /\.svg$/,
+        use: '@svgr/webpack'
+      })
+
+      config.module.rules.push({
+        test: /\.mdx?$/,
+        use: [
+          options.defaultLoaders.babel,
+          require.resolve('./mdx-loader')
+        ]
+      })
+
+      /**
+       * in production we don't have access to ../modules, so we need to
+       * rewrite the 'primer/index.scss' import to the static CSS build
+       */
+      if (!dev) {
+        config.resolve.alias[PRIMER_SCSS] = PRIMER_STATIC_CSS
+        // only log the aliasing once
+        if (!configured) {
+          console.warn(`*** rewriting ${PRIMER_SCSS} to ${PRIMER_STATIC_CSS}`)
+        }
+      }
+
+      configured = true
+      if (typeof nextConfig.webpack === 'function') {
+        return nextConfig.webpack(config, options)
+      }
+
+      return config
+    }
+  })
+}

docs/lib/each.js

@@ -0,0 +1,8 @@
+module.exports = function each(fn) {
+  return (files, metal, done) => {
+    for (const path of Object.keys(files)) {
+      fn(files[path], path, metal)
+    }
+    done()
+  }
+}