Merge pull request #671 from primer/release-12.0.0

Release 12.0.0

.browserslistrc

@@ -0,0 +1,6 @@
+> 5%
+last 2 firefox versions
+last 2 chrome versions
+last 2 safari versions
+last 2 edge versions
+ie 11

.eslintrc.json

@@ -0,0 +1,13 @@
+{
+  "extends": [
+    "plugin:github/es6",
+    "plugin:github/recommended"
+  ],
+  "env": {
+    "es6": true,
+    "node": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2017
+  }
+}

.github/main.workflow

@@ -0,0 +1,42 @@
+workflow "lint, test, deploy, publish" {
+  on = "push"
+  resolves = [
+    "lint",
+    "test",
+    "publish",
+    "deploy",
+  ]
+}
+
+action "install" {
+  uses = "actions/npm@v2.0.0"
+  args = ["install", "--unsafe-perm"]
+}
+
+action "lint" {
+  needs = "install"
+  uses = "actions/npm@v2.0.0"
+  args = ["--unsafe-perm", "run", "lint"]
+}
+
+action "test" {
+  needs = "install"
+  uses = "actions/npm@v2.0.0"
+  args = ["--unsafe-perm", "test"]
+}
+
+action "publish" {
+  needs = ["lint", "test"]
+  uses = "primer/publish@v1.0.0"
+  args = ["--", "--unsafe-perm"]
+  secrets = ["GITHUB_TOKEN", "NPM_AUTH_TOKEN"]
+}
+
+action "deploy" {
+  needs = "install"
+  uses = "primer/deploy@v2.2.0"
+  secrets = [
+    "GITHUB_TOKEN",
+    "NOW_TOKEN",
+  ]
+}

.github/pull_request_template.md

@@ -1,6 +1,8 @@
-- [ ] First, briefly describe your proposal in the title.
+First, briefly describe your proposal in the title and delete this line.
 
-- [ ] Fixes: #  (type an issue number after the # if applicable)
+If your proposal fixes any issues, please list them below, then delete this line:
+
+-  Fixes: # (type an issue number after the # if applicable)
 
 Finally, tell us more about the change here, in the description.
 

.gitignore

@@ -1,10 +1,10 @@
-*.lerna_backup
 *.log
-*/*/package-lock.json
+*.tgz
 .DS_Store
 .changelog
+.next/
 .sass-cache
 _site
-build
-primer-version.txt
-node_modules
+build/
+dist/
+node_modules/

.npmignore

@@ -1,2 +1,15 @@
-*.yml
-.postcss.json
+*.log
+.github/
+.next/
+.storybook/
+next.config.js
+now.json
+docs/
+docs-test/
+lib/
+pages/
+script/
+# we ignore this because everything in src/ is copied out in script/prepublish
+src/
+static/
+tests/

.npmrc

@@ -1,3 +1,3 @@
 save=true
 save-exact=true
-no-package-lock=true
+git-tag-version=false

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 12.0.0
+
+:rotating_light: **Starting with version 12.0.0, the `primer` package is now known as `@primer/css`**. See [MIGRATING.md](https://github.com/primer/css/tree/master/MIGRATING.md) for more info.
+
+#### :boom: Breaking Change
+* [#666](https://github.com/primer/css/pull/666) Reorganize into a single `@primer/css` package ([@shawnbot](https://github.com/shawnbot))
+
 # 11.0.0
 
 #### :boom: Breaking Change

DEVELOP.md

@@ -1,50 +1,107 @@
 # Primer Development
 
-If you've made it this far, **thank you**! We appreciate your contribution, and hope that this document helps you along the way.
+If you've made it this far, **thank you**! We appreciate your contribution, and hope that this document helps you along the way. If you have any questions or problems, don't hesitate to [file an issue](https://github.com/primer/css/issues/new).
 
 ## Structure
-The project is structured as a [monorepo] made up of lots of small npm modules, many of which depend on each other. We use [Lerna] to manage, version, and publish all of the packages together.
+Primer CSS is published to [npm] as [@primer/css]. Each of Primer CSS's "modules" lives in a subfolder under `src/` with an `index.scss` in it. Generally speaking, the styles are divided into three primary themes:
+
+* **Core** styles (in `core/`) are common dependencies, which include support variables, native element and typography styles, buttons, navigation, tooltips, etc.
+* **Product** styles (in `product/`) are specific to github.com, and include components such as avatars, labels, markdown styles, popovers, and progress indicators.
+* **Marketing** styles (in `marketing/`) are specific to GitHub marketing efforts, including international and event-focused sites as well as the more design-heavy feature pages on github.com. Marketing styles include new colors and button styles, and extend the core typography and whitespace scales.
+
+### Paths
+Here's what you need to know about how the files are structured in both git and in the published npm module:
+
+* In git, all of the SCSS source files live in the `src/` directory.
+* When published, all of the files in `src/` are "hoisted" to the package root so that you can import, say, utilities with:
+
+    ```scss
+    @import "@primer/css/utilities/index.scss";
+    ```
+
+* All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with `../`), so everything should work fine as long as the `@primer/css` directory is in one of your Sass include paths (i.e. `node_modules`).
 
-The top-level `package.json` is not published, but tracks common dependencies for developing Primer, and hosts some useful npm [run-scripts]. See the [scripts section](#scripts) for more info.
 
 ## Workflow
 The typical Primer workflow looks something like this:
 
-1. [Install](#install)
-2. [Start Storybook](#storybook)
-3. Navigate to the module you're working on and modify the SCSS and/or markdown files.
-4. Test your changes in Storybook.
-5. Push your work to a new branch to test it on Travis and have it reviewed by the Primer "core" team.
+1. `npm install` to install the development dependencies.
+1. [Start Storybook](#storybook)
+1. Navigate to the module you're working on and modify the SCSS and/or markdown files.
+1. Test your changes in Storybook.
+1. Push your work to a new branch.
+1. Request a review from one of the Primer "core" team members.
 
 ## Install
-Run `npm install` to install the npm dependencies and automatically run link all of the local packages together with `npm run bootstrap`.
+Run `npm install` to install the npm dependencies.
 
-### Troubleshooting install problems
-If you run into trouble installing, it's always best to ensure that you're starting from a clean slate by running the following from the repository root directory:
+## Docs site
+The Primer CSS docs are built with React using [Primer Components](https://primer.style/components) and automatically deployed on every push to this repo using our [primer/deploy action](/primer/deploy). You can run the server locally with:
 
 ```sh
-npm run fresh
+npm start
 ```
 
-If _that_ gives you problems, then you can try manually deleting everything and starting over:
+Then visit http://localhost:3000/css to view the site.
 
-```
-rm -rf node_modules
-rm -f package-lock.json */*/package-lock.json
-npm install
-```
+:rotating_light: **Warning:** Next.js has a [long-running issue](https://github.com/zeit/next.js/issues/1189) with trailing slashes in URLs. Avoid visiting `http://localhost:3000/` if possible, as this may cause your development server to fail in less-than-graceful ways.
+
+
+### Syncing the docs
+Both before and while the Next dev server runs, all of the Markdown files within the `src/` directory are synced to Next's `pages/` directory and rewritten to include useful metadata.
+
+If, for whatever reason, the dev server isn't syncing files from `src/` to `pages/`, you have two choices:
+
+1. Stop the server (`ctrl-C`) and restart it (`npm start`), 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 [css subdirectory](./pages/css).
+
+The sync task maintains a list of files copied from `src/` in `pages/css/.gitignore`, which ensures that none of these generated files are checked into git.
 
-**You may need to do this whenever switching between branches with different dependencies, submodules, or versions of Node and/or npm.** The Primer core team generally uses the latest major version of Node (10 as of this writing), but our CI tests run Node 8 and npm 6. You can check which versions you're running with:
+### 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 (`**/*.md`).
+1. Many bundle `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. 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.
+
+### URL tests
+We have a script that catches inadvertent URL changes caused by renaming or deleting Markdown docs:
 
 ```sh
-npm --version
-node --version
+npm run test-urls
 ```
 
+This script includes some exceptions for URLs that have been intentionally moved or removed in the process of moving away from the [GitHub Style Guide](https://styleguide.github.com/primer/), and which you will need to modify if you rename or remove either Markdown docs or their `path` frontmatter. See [#641](https://github.com/primer/css/pull/641) for more information.
+
 ## Storybook
-Run `npm start` to start up [Storybook], then visit [localhost:3000](http://localhost:3000) to test your work. By default, all `html` code blocks of all `*.md` files in each module will be rendered as stories and listed under the module's name in the left-hand nav. File changes should trigger live reload automatically after a brief delay.
+To borrow a [metaphor from Brad Frost](http://bradfrost.com/blog/post/the-workshop-and-the-storefront/), the [docs site](#docs-site) is Primer CSS's storefront, and [Storybook] is its workshop.
+
+Our Storybook setup allows you to view every HTML code block in Primer CSS's Markdown docs in isolation. To get started, run the Storybook server with:
+
+```sh
+npm run start-storybook
+```
+
+Then visit http://localhost:8000 to test your work.
 
-If the package you're working on has a `stories.js`, it probably includes a snippet like this:
+### Code blocks
+All `html` fenced code blocks in `src/**/*.md` will be rendered as stories and listed under the relevant module's name in the left-hand nav. File changes should trigger a live reload automatically (after a brief delay).
+
+If the bundle you're working on has a `stories.js`, it probably includes a snippet like this:
 
 ```js
 const stories = storiesOf('Module name', module)
@@ -55,34 +112,31 @@ storiesFromMarkdown(require.context('.', true, /\.md$/))
   })
 ```
 
-This is how we find all of the Markdown files in the package directory and generate stories from their code blocks. Storybook sections are labeled by the first argument to `storiesOf()` (in the above example, "Module name"), and individual stories get their titles from either the previous Markdown heading or the `title` attribute in the fenced code block. See the [`code-blocks` docs](https://npmjs.com/package/code-blocks) and the [`storiesFromMarkdown()` source](./.storybook/lib/storiesFromMarkdown.js) for more info.
-
-## CSS packages
-All of the Primer CSS packages live in the [modules](./modules) subdirectory, including the [`primer`](./modules/package) omnibus package.
-
-## Tools
-Many tools specific to development of Primer CSS live in the [tools](./tools) subdirectory. 
+This is how we find all of the Markdown files in the bundle directory and generate stories from their code blocks. Storybook sections are labeled by the first argument to `storiesOf()` (in the above example, "Module name"), and individual stories get their titles from either the previous Markdown heading or the `title` attribute in the fenced code block. See the [`code-blocks` docs](https://npmjs.com/package/code-blocks) and the [`storiesFromMarkdown()` source](./.storybook/lib/storiesFromMarkdown.js) for more info.
 
 ## Scripts
-The [`script` directory](./script) houses a collection of scripts that we use to maintain, test, build, and publish packages. Some scripts of note:
+Our [`package.json`](package.json) houses a collection of [run-scripts] that we use to maintain, test, build, and publish Primer CSS, notably:
 
-* `script/check-imports` compares the list of Primer npm dependencies for each package with SCSS `@import` statements in its source, and warns if any mismatches (dependencies without corresponding imports, or vice-versa) are found.
-* `script/compare-published` compares the latest published versions of each Primer CSS package with the `version` field in its local `package.json`, and reports any discrepancies.
-* `script/get-packages` lists all of the package subdirectories from both `modules` and `tools` directories, and is useful for iterating in shell scripts:
+* `dist` runs `script/dist`, which creates CSS bundles of all the `index.scss` files in `src/`.
+* `check-links` runs a link checker on your local development server (`localhost:3000`, started with `npm start`).
+* `lint` lints all of our SCSS source files.
+* `lint-js` lints the docs site and supporting scripts.
+* `now-build` and `now-start` are run on [Now] to build and start the docs site server.
+* `sync` copies Markdown docs from `src/` to `pages/css/` and preps them for inclusion in the docs site.
+* `test-urls` compares a (pre-generated) list of paths from the [Primer Style Guide](https://styleguide.github.com/primer/) to files in `pages/css`, and lets us know if we've inadvertently deleted or renamed anything.
+* `test-migrate` tests the [`primer-migrate`](MIGRATING.md#primer-migrate) command line utility.
+* `watch` runs the sync script in watch mode, copying files as they're changed from `src/` to `pages/css/`.
 
-    ```sh
-    for pkg in $(script/get-packages); do
-      echo $pkg
-    done
-    ```
-
-    If you're looking for more detail, you can also run `npx lerna ls`, which will list the packages by name along with their versions.
-
-Scripts like `lint-scss`, `notify`, and `test-docs` are called from individual packages to run specific common tasks; `npm-run` and `npm-run-all` are used more generally to run monorepo-installed npm utilities within the package directory, and can probably be refactored to simply run [npx].
+You can list all of the available scripts with:
+
+```sh
+npm run
+```
 
 
-[monorepo]: https://github.com/babel/babel/blob/master/doc/design/monorepo.md
-[Lerna]: https://github.com/lerna/lerna
+[@primer/css]: https://www.npmjs.com/package/@primer/css
+[metalsmith]: https://metalsmith.io/
 [run-scripts]: https://docs.npmjs.com/cli/run-script
-[Storybook]: https://storybook.js.org/
+[storybook]: https://storybook.js.org/
+[npm]: https://www.npmjs.com/
 [npx]: https://www.npmjs.com/package/npx