Merge pull request #631 from primer/docs-release-fixes

Docs release fixes

.travis.yml

@@ -10,34 +10,49 @@ env:
     - secure: "KcGydAqL7ryDh2rTJJB4wU8NE5BRtnrRXDEcPBScSscO3zFsHXHBDvvO04B/9hFVatXzGYXmkn+FZ0P9QikhvebzdwwyqUG2SKFiHhMvbX0m0WtAhn5NqDuKU1r5qy5YQ18r/tiLfC9GSAlEpfLAH58pwpcn8srV3Mn/yKvlrfs="
 
 script:
-  - script/build-docs
   - 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
+  # (the script will bail on release branches and master)
   - provider: script
-    script: script/release-candidate
+    script: script/release-pr --yes
     skip_cleanup: true
     on:
-      branch: release*
+      all_branches: true
+      tags: false
+
+  # publish release candidates on release branches
+  - provider: script
+    script: script/release-candidate --yes
+    skip_cleanup: true
+    on:
+      branch: release-*
       tags: false
 
   # publish "final" releases on master
   - provider: script
-    script: script/release
+    script: script/release --yes
     skip_cleanup: true
     on:
       branch: master
       tags: false
 
+  # lastly, deploy the docs site with whatever was published
+  - provider: script
+    script: script/deploy-docs
+    skip_cleanup: true
+    on:
+      all_branches: true
+      tags: false
+
 notifications:
   slack:
     secure: W9lPRuuPMNwElkXZ8UZtu5phgUNleDCK0PgERa28dkh5b0Y9xzRpIQPRJfqVYAPtnMVXhfYcqryMzA4oj0E4fc7OxQsKmMeF1OcTuj5N4CM5xXR/qXDehOUTp6fpCToIX9d4hZ2H///PCExpul3TcfxYJe6EWQCHYd1n6zKRl8g=

docs/now.json

@@ -9,7 +9,7 @@
     }
   },
   "engines": {
-    "node": ">=10"
+    "node": "8"
   },
   "files": [
     "copy.js",

docs/pages/css/getting-started/contributing.md

@@ -148,65 +148,11 @@ The status option is a tag that will tag a module as a thing, displaying what st
 
 ```yml
 ---
-source: /app/assets/stylesheets/primer-product/avatars/lib/avatar-stack.scss
+source: https://github.com/github/github/tree/master/app/assets/stylesheets/components/x.scss
 ---
 ```
 
-The source option will let you point the document to the source file. This will then display a link in the styleguide to the sourcefile.
+The source option will let you point the document to the source file. **This is only necessary for components that still live in the `github/github` repo**; Primer CSS source files will have the `source` field populated automatically.
-
-```yml
----
-homepage: https://github.com/primer/primer
----
-```
-
-Homepage is useful for when you want to point a guide to public source code. When it exists the source icon and link will be displayed publicly.
-
-```yml
----
-draft: true
----
-```
-
-When a section is public, but you want to keep some of the sections in the guide private, you can set `draft: true`. This will only show that guide to users who meet the `draft_user?` criteria.
-
-### Sorting articles
-
-```yml
-# These sort arrays would manual sort these items above the other items in the
-# page. The rest of the articles will be sorted alphabetically
-
-# Sort topic sections
-css:
-  - support
-
-# Sort section articles
-css/codestyle:
-  - principles
-  - SCSS
-```
-
-You have the ability to sort the articles manually within each section. create an array with the key that is the styleguide path of the section, ie `css/codestyle` is the array, with `principles` being sorted first.
-
-By default the articles inside each section are sorted alphabetically. When you land on a page like /styleguide/ruby
-
-What you see is something like this.
-
-```
-1. README - _the README for the section is always stuck up top, with no sidebar nav_
-2. Article A
-3. Article B
-4. Article C
-```
-
-If you add an article to the `.sort.yml` file, then that section will be sorted above the alphabetical section, according to the index of the article in the yml array.
-
-```
-1. README - _the README for the section is always stuck up top, with no sidebar nav_
-2. Article B - `sort: 1`
-3. Article C - `sort: 2`
-4. Article A
-```
 
 ### Special tags
 
@@ -305,64 +251,4 @@ To publish, there are two requirements. First, you must be on the `master` branc
 
 All the individual Primer modules are [semver](http://semver.org/) versioned. This helps others know when a change is a patch, minor, or breaking change.
 
-When you're ready to cut a new release for a specific module, you'll want to update that module's version number in the `package.json` file inside of the `github/github` repository.
-
-To help determine what version number to update for the modules, there's a command in `script/css-modules --version` that will interactively step through each module, show you what's changed, and ask if you would like to make a `(M)ajor, M(i)nor, (P)atch` update. The output will look something like this:
-
-```
-Changes to primer-navigation since last version 0.3.0:
-
- * Updating link to real primer repository - Jon Rohan [github/github@bbaedda](https://github.com/github/github/commit/bbaedda)
- * Updating the modules stylelint - Jon Rohan [github/github@389609f](https://github.com/github/github/commit/389609f)
- * move over all bold variable changes - Mark Otto [github/github@6b5b021](https://github.com/github/github/commit/6b5b021)
-
-Do you want to create a new version? (M)ajor, M(i)nor, (P)atch, (S)kip i
- [✓] Updated version number to 0.4.0
-```
-
 To understand what choice to make, you'll need to understand semver and know if one of the changes shown is a major, minor, or patch. Semver is confusing at first, so I recommend reviewing [semver](http://semver.org/) and/or ask in [#design-systems](https://github.slack.com/archives/design-systems) or and experienced open-source contributor.
-
-**Running through this script is not required**, but it helps updating the version numbers across all the modules. Afterwards you should have a bunch of updated version numbers in the modules.
-
-### Publishing
-
-After you've [versioned](#versioning) your modules and the new version numbers are on the `master` branch. You're ready to publish those modules to the primer org.
-
-To begin publishing, run `script/css-modules --publish`. This will publish all the commits since the last publish to the primer org.
-
-If any of the modules fail to publish, the script will fail out for that module, and continue with the next.
-
-### NPM
-
-We publish the modules to NPM to make them easy for others to use. You won't need to do anything for this to happen. Once you've [published](#publishing) the module. [TravisCI](https://travis-ci.org/primer) takes over. It runs lint tests on the code, then auto publishes the module to npm.
-
-
-## Ship checklist
-
-Our CSS framework—[Primer](http://primercss.io/)—is published to [NPM](https://www.npmjs.com/package/primer) and the [Primer organization](https://github.com/primer) on GitHub. When changes are made to primer-core, primer-product, or primer-marketing modules, a few steps are required to keep the framework up-to-date and reliable for everyone to use.
-
-### Required steps
-- update the style guide [changelog](../changelog) with a link to the corresponding pull request
-- update the Primer module version number according to the [semantic versioning system](http://semver.org/)
-- add the labels `design-systems` and `status: review needed` to your pull request, and ensure a design systems [core maintainer](https://github.com/github/design-systems/#core-maintainers) reviews the changes before shipping
-- run the publish script once changes are merged into master, if you hit any issues with this please reach out to the [design systems team](https://github.com/github/design-systems)
-
-### Optional steps
-Depending on the changes made, you may need to complete these additional steps:
-- add a new repo to the [Primer organization](https://github.com/primer) if you are adding a new module
-- update the style guide [status](/css#status) in the documentation if the status of the module has changed, and if needed, create a new [feedback issue](https://github.com/github/design-systems/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+feedback%22) in the design systems repo and link it to the documentation
-- add documentation when adding a new module, or update documentation if code changes to class names or other implementation details have changed
-- write a team post if changes are significant, ask a [core maintainer](https://github.com/github/design-systems/#core-maintainers) to review before posting
-
-To make it clear to reviewers, add the following checklist to your pull request description (edit items as needed):
-
-```md
-### Ship checklist
-- [ ] Update documentation
-- [ ] Update status label
-- [ ] Update Changelog.md
-- [ ] Update primer module version number
-- [ ] Add repo to Primer organization
-- [ ] Run publish script to update Primer modules
-- [ ] Write team post
-```

docs/pages/css/getting-started/index.md

@@ -1,6 +1,5 @@
 ---
 title: Getting started
-sidebar: {root: true}
 ---
 
 Our CSS framework, Primer, is [open-sourced on GitHub](https://github.com/primer/primer) and [hosted on npm](https://www.npmjs.com/package/primer). Our modules are grouped into three packages: [primer-core](https://github.com/primer/primer/tree/master/modules/primer-core), [primer-product](https://github.com/primer/primer/tree/master/modules/primer-product), and [primer-marketing](https://github.com/primer/primer/tree/master/modules/primer-marketing). `primer-core` contains packages used in both product (github.com) and marketing (logged out homepage). To install all of primer, you can use [primer](https://github.com/primer/primer) which is a grouping of core, product and marketing.

docs/pages/css/principles/index.md

@@ -1,6 +1,5 @@
 ---
 title: Principles
-sidebar: {root: true}
 ---
 
 The CSS styleguide enables us to create a consistent user experience across GitHub, manage CSS bloat, and make our CSS easier to maintain. These principles should serve as guidelines for how we write and use CSS.

modules/primer/scripts/postpublish.js

@@ -0,0 +1,6 @@
+const fs = require('fs')
+const {join} = require('path')
+
+const version = require('../package.json').version
+const path = join(__dirname, '../../../VERSION')
+fs.writeFileSync(path, version, 'utf8')

script/after_success

@@ -1,11 +0,0 @@
-#!/bin/bash
-set -e
-
-branch=$TRAVIS_PULL_REQUEST_BRANCH
-event=$TRAVIS_EVENT_TYPE
-
-# only publish canary releases on non release or master branches
-if [[ "$event" = "pull_request" ]] && [[ !("$branch" =~ ^release-.*) ]] && [[ !("$branch" = "master") ]];
-then
-  script/release-pr --yes
-fi

script/build-docs

@@ -1,20 +0,0 @@
-#!/bin/bash
-set -e
-
-if [ -z "$NOW_TOKEN" ]; then
-    echo "NOW_TOKEN is not set; skipping docs deployment"
-else
-    cp modules/primer/build/build.css docs/static/primer.css
-    cd docs
-    npm run sync
-    now="now --token=$NOW_TOKEN"
-    $now | tee now-url.txt
-    url=$(cat now-url.txt)
-    version=$(jq -r .version ../modules/primer/package.json)
-    npx commit-status success docs "deployed primer@$version to $url" "$url"
-    alias="primer-css-$TRAVIS_BRANCH.now.sh"
-    echo "aliasing..."
-    $now alias $url $alias
-    url="https://$alias"
-    npx commit-status success docs "deployed primer@$version to $url" "$url"
-fi

script/deploy-docs

@@ -0,0 +1,45 @@
+#!/bin/bash
+set -e
+
+if [ -z "$NOW_TOKEN" ]; then
+    echo "NOW_TOKEN is not set; skipping docs deployment"
+else
+    if [[ -e VERSION ]]; then
+        version=$(cat VERSION)
+    else
+        version=$(jq -r .version modules/primer/package.json)
+    fi
+
+    cp modules/primer/build/build.css docs/static/primer.css
+    cd docs
+    npm run sync
+
+    actual=$(jq -r .dependencies.primer package.json)
+
+    if [[ "$version" != "$actual" ]]; then
+        # here, we need to manually update the primer dependency
+        # version to the one that we published
+        echo "primer has '$version' in package.json; docs wants '$actual'"
+        jq ".dependencies.primer = \"$version\"" package.json > package.json.tmp
+        mv package.json.tmp package.json
+    fi
+
+    now_args="--token=$NOW_TOKEN"
+    npx commit-status pending docs "deploying primer@$version with now..."
+
+    echo "deploying..."
+    now $now_args | tee now-url.txt
+    url=$(cat now-url.txt)
+    npx commit-status success docs "deployed primer@$version to $url" "$url"
+
+    if [[ $TRAVIS_EVENT_TYPE = "pull_request" ]]; then
+        branch=$TRAVIS_PULL_REQUEST_BRANCH
+    else
+        branch=$TRAVIS_BRANCH
+    fi
+
+    alias="primer-css-${branch//\./-}.now.sh"
+    echo "aliasing to '$alias'..."
+    now $now_args alias $url $alias
+    npx commit-status success docs "primer@$version docs: $url" "https://$alias"
+fi

script/get-packages

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
 const fs = require('fs')
 const globby = require('globby')
-const path = require('path')
+const {join} = require('path')
 
-const getPackages = (debug) => {
+const getPackages = (debug = false) => {
   const lernaConfig = require('../lerna.json')
-  const packageGlobs = lernaConfig.packages
+  const packageGlobs = lernaConfig.packages.concat('!**/*.md')
   return globby(packageGlobs)
     .then(packagePaths => {
+      if (debug) {
+        console.warn(`Filtering ${packagePaths.length} paths...`)
+      }
       return packagePaths.filter(pkg => {
         try {
-          require.resolve(`../${pkg}/package.json`)
+          require.resolve(join('..', pkg, 'package.json'))
           return true
         } catch (error) {
           if (debug) {
-            console.warn('No package.json in %s', pkg)
+            console.warn(`No package.json in ${pkg}: ${error}`)
           }
+          return false
         }
       })
     })

script/is-prerelease

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -e
+head=$(git symbolic-ref --short HEAD)
+branch=${TRAVIS_PULL_REQUEST_BRANCH:-$head}
+expected=${branch/release-/}
+actual=$(jq -r .version modules/primer/package.json)
+echo "branch: 'release-$expected' vs. primer/package.json '$actual'"
+if [[ "$expected" = "$actual" ]]; then
+    echo "+ match!"
+    exit 0
+else
+    echo "x mismatch."
+    exit 1
+fi

script/release

@@ -1,15 +1,12 @@
 #!/bin/bash
 set -e
+
 echo "📦  Publishing latest release..."
 
 # note: try-publish should exit cleanly if it detects a duplicate
 # published version
-$(npm bin)/lerna exec -- $(pwd)/script/try-publish
+npx lerna exec $@ -- script/try-publish
 
 # Build and publish storybook
-$(npm bin)/build-storybook -o build
+npx build-storybook -o build
 script/publish-storybook
-
-echo "📓  Updated CHANGELOG..."
-
-$(npm bin)/lerna-changelog

script/release-candidate

@@ -1,165 +1,14 @@
-#!/usr/bin/env node
+#!/bin/bash
-const execa = require('execa')
+set -e
-const fetch = require('isomorphic-fetch')
-const fse = require('fs-extra')
-const registryUrl = require('registry-url')
-const semver = require('semver')
 
-const bin = 'node_modules/.bin/'
+if [[ "$@" = "--dry-run" ]]; then
-const lernaBin = `${bin}lerna`
+  publish_args="--skip-git --skip-npm"
-const getPackages = require('./get-packages')
+else
-const getReleaseVersion = require('./get-release-version')
+  publish_args=$@
-const revertPackages = require('./revert-packages')
+fi
 
-const PRERELEASE = 'prerelease'
+echo "🦜 Publishing canary release..."
-const DIST_TAG = 'rc'
+npx lerna publish --canary --exact --npm-tag=rc $publish_args
-const PRIMER_CSS = 'primer'
-const RELEASE_VERSION = getReleaseVersion(
-  PRIMER_CSS,
-  process.env.TRAVIS_BRANCH
-)
 
-const dryRun = process.argv.slice(2).indexOf('--dry-run') > -1
+echo "📓  Generating CHANGELOG..."
-
+npx lerna-changelog
-const depFields = [
-  'dependencies',
-  'devDependencies',
-  'optionalDependencies',
-  'peerDependencies',
-]
-
-const getUpdated = () => {
-  return execa(lernaBin, ['updated', '--json'], {
-      reject: false
-    })
-    .then(res => {
-      if (res.stdout == '') {
-        console.warn('No packages need updating')
-        return []
-      } else {
-        return JSON.parse(res.stdout)
-      }
-    })
-    .then(updated => updated.map(pkg => pkg.name))
-}
-
-const writePackage = (pkg) => {
-  const {dir} = pkg
-  delete pkg.dir
-  const json = JSON.stringify(pkg, null, '  ') + '\n'
-  pkg.dir = dir
-  return fse.writeFile(`${pkg.dir}/package.json`, json, 'utf8')
-    .then(() => pkg)
-}
-
-const bump = (pkg, by, preid) => {
-  if (pkg.name === PRIMER_CSS) {
-    pkg.version = RELEASE_VERSION
-  }
-
-  const original = pkg.version
-  let version = increment(pkg.version, by, preid)
-  return getPackageInfo(pkg.name)
-    .then(info => {
-      while (version in info.versions) {
-        version = increment(version, by, preid)
-      }
-      console.warn('%s %s -> %s', pkg.name, original, version)
-      pkg.version = version
-      return writePackage(pkg)
-    })
-}
-
-const getPackageInfo = (name) => {
-  const url = registryUrl() + name
-  return fetch(url).then(res => res.json())
-}
-
-const increment = (version, by, preid) => {
-  const {major, minor, patch} = semver(version)
-  const prev = [major, minor, patch].join('.')
-  const next = semver.inc(version, by, preid)
-  // if this is a prerelease, 'revert' major.minor.patch
-  // so that only the prerelease id is incremented
-  return by === PRERELEASE
-    ? next.replace(/^\d+\.\d+\.\d+/, prev)
-    : next
-}
-
-const updateDependants = (pkg, pkgs) => {
-  return pkgs.filter(other => {
-    let changed = false
-    depFields.forEach(field => {
-      if (other[field] && (pkg.name in other[field])) {
-        other[field][pkg.name] = pkg.version
-        changed = true
-      }
-    })
-    return changed
-  })
-}
-
-revertPackages()
-  .then(() => getPackages())
-  .then(dirs => {
-    return dirs.map(dir => {
-      const pkg = require(`../${dir}/package.json`)
-      pkg.dir = dir
-      return pkg
-    })
-  })
-  .then(pkgs => {
-    const by = PRERELEASE
-    const preid = DIST_TAG
-    return getUpdated()
-      .then(updated => {
-        console.warn('%d packages updated...', updated.length)
-        return pkgs.filter(pkg => updated.includes(pkg.name))
-      })
-      .then(updated => {
-        const changed = new Set(updated)
-        return Promise.all(updated.map(pkg => {
-          return bump(pkg, by, preid)
-            .then(pkg => updateDependants(pkg, pkgs))
-            .then(dependants => {
-              dependants.forEach(dep => changed.add(dep))
-            })
-        }))
-        .then(() => {
-          const tasks = Array.from(changed)
-            .map(writePackage)
-          return Promise.all(tasks)
-        })
-        .then(updated => {
-          const tasks = updated.map(pkg => {
-            const command = 'npm'
-            const args = ['publish', '--tag', DIST_TAG]
-            if (dryRun) {
-              console.log('publish:', pkg.name, '@', pkg.version, 'in:', pkg.dir)
-              return
-            }
-            return execa(command, args, {
-              cwd: pkg.dir,
-              stdio: 'inherit',
-            })
-          })
-          return Promise.all(tasks)
-        })
-        .then(() => {
-          console.warn('📓  Updated CHANGELOG...\n')
-          return execa(`${bin}lerna-changelog`, [], { env: process.env })
-            .then(result => {
-              console.warn(result.stdout)
-            })
-            .catch(error => {
-              console.error('lerna-changelog error:', error)
-            })
-        })
-      })
-  })
-  .catch(error => {
-    console.error('Error:', error)
-    process.exitCode = 1
-    return
-  })
-  .then(() => process.exit())

script/release-pr

@@ -1,9 +1,16 @@
 #!/bin/bash
 set -e
-echo "🐦  Publishing PR (canary) release..."
 
-$(npm bin)/lerna publish --npm-tag=pr --canary --exact $@
+branch=$TRAVIS_PULL_REQUEST_BRANCH
 
-echo "📓  Updated CHANGELOG..."
+if [[ "$branch" = "master" ]]; then
+    reason="this is the master branch"
+elif [[ "$branch" =~ ^release- ]]; then
+    reason="this is a release branch"
+else
+    echo "🐦  Publishing PR (canary) release..."
+    npx lerna publish --canary --exact --npm-tag=pr $@
+    exit 0
+fi
 
-$(npm bin)/lerna-changelog
+echo "Skipping PR release because $reason (TRAVIS_PULL_REQUEST_BRANCH = '$branch')"