Improve contributing docs and add DEVELOP.md

.github/CONTRIBUTING.md

@@ -71,110 +71,8 @@ Here are a few things you can do that will increase the likelihood of your pull
 - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
 - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
-## Releasing a new Primer version 🎉
-
-This section is targeted at maintainers of primer, to instruct them on the processes for releasing a new version.
-
-### In `primer/primer`:
-
-1. Find or create a new pull request with a release branch from `master` and name it `release-<version>`.
-
- (CI will publish a release candidate version to npm for branches prefixed with `release`. These version numbers have a `rc.<number>` suffix on them)
-
- For the pull request you can use the following template.
-
- ```md
-  # Primer Minor Release
-
-  Tracking Issue for next release: 📦 **0.0.0**
-  Approximate release date: 📆
-
-  ### Must
-
-  - [ ]
-
-  ### Should
-
-  - [ ]
-
-  ### Could
-
-  - [ ]
-
-  ----
-
-  ### Ship checklist
-
-  - [ ] Update CHANGELOG
-  - [ ] Run version bump
-  - [ ] Update primer.github.io
-  - [ ] Update github/github
-  - [ ] Update the style guide
-  - [ ] Update the release tag note
-  - [ ] Create a new pull request for the next release
-
-  /cc @primer/ds-core
- ```
-
-2. Go through the tracking issue and make sure everything that should be merged in is merged in.
-
-3. Once your builds finish, click on the details links for the continuous-integration/travis-ci/push build.  Expand the `Deploying application` output and you should be able to find an outputted change log here. Copy this and update the [CHANGELOG.md](https://github.com/primer/primer/blob/master/CHANGELOG.md) file.
-
-4. Run the version bump in your terminal: `npm run bump`.
-
-5. Test your changes with the latest release candidate version in the appropriate places (styleguide, storybook, github/github).
-
-6. Once the release PR is approved and you've done necessary testing, merge to `master`. This will trigger a publish to npm.
-
-### In `github/github`:
-
-1. Create a new branch
-
-2. Update the primer version in your terminal  `bin/npm install primer@<version>`.
-
-3. Update `stylelint-config-primer` in your terminal to the appropriate version `bin/npm install stylelint-config-primer@latest`.
-
-4. If you need to make changes to github/github due to the Primer release, make a separate branch. When ready, merge that branch into your release branch.
-
-5. Add reviewers.
-
-6. Check that every deleted vendor file has an accompanying updated vendor file and that the version numbers look correct.
-
-7. Test on review-lab.
-
-8. When ready, merge! 🎉
-
-
-## Other items that need to be done after publishing Primer
-
-#### Update the Style Guide
-
-1. In [github/styleguide](https://github.com/github/styleguide), update `primer` to your newly released version in your terminal:
-
-  `npm install primer@latest`
-
-2. Then  run: `script/update-primer-docs`.
-
-3. Commit changes, make PR, get it approved, merge! 🚀
-
-#### Update [primer.github.io](primer.github.io)
-
-1. Edit  [index.html](https://github.com/primer/primer.github.io/blob/master/index.html) to include the latest version.
-
-#### Update Storybook
-
-1. Pull the latest from master on primer/primer (after merging in release branch).
-
-2. Run `npm run publish-storybook`.
-
-#### Publish release tag
-
-1. Create a new release tag [here](https://github.com/primer/primer/releases/new).
-
-2. Copy the changes from the [CHANGELOG](https://github.com/primer/primer/blob/master/CHANGELOG.md) and paste it into the release notes.
-
-3. Publish 🎉
-
+## Releasing a new Primer version
+See [RELEASING.md](../RELEASING.md) for our release process.
 
 ## Resources
 

DEVELOP.md

@@ -0,0 +1,82 @@
+# 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.
+
+## 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.
+
+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.
+
+## Install
+Run `npm install` to install the npm dependencies and automatically run link all of the local packages together with `npm run bootstrap`.
+
+### 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:
+
+```sh
+npx lerna clean --yes
+rm -rf node_modules
+npm install
+```
+
+**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 we run our CI tests on Node 8 and npm 6. You can check which versions you're running with:
+
+```sh
+npm --version
+node --version
+```
+
+## 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.
+
+If the package you're working on has a `stories.js`, it probably includes a snippet like this:
+
+```js
+const stories = storiesOf('Module name', module)
+
+storiesFromMarkdown(require.context('.', true, /\.md$/))
+  .forEach(({title, story}) => {
+    stories.add(title, story)
+  })
+```
+
+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. 
+
+## Scripts
+The [`script` directory](./script) houses a collection of scripts that we use to maintain, test, build, and publish packages. Some scripts of note:
+
+* `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:
+
+    ```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].
+
+
+[monorepo]: https://github.com/babel/babel/blob/master/doc/design/monorepo.md
+[Lerna]: https://github.com/lerna/lerna
+[run-scripts]: https://docs.npmjs.com/cli/run-script
+[Storybook]: https://storybook.js.org/
+[npx]: https://www.npmjs.com/package/npx

README.md

@@ -46,35 +46,21 @@ Then, you would import the module with:
 @import "primer-navigation/index.scss";
 ```
 
-Or, while you're figuring out which modules you need, you can import them directly from the `primer` [`modules` directory](./modules) like so:
-
-```scss
-@import "primer/modules/primer-navigation/index.css";
-```
-
-
-## Build
-
-For a compiled **CSS** version of this module, an npm script is included that will output a CSS version to `build/build.css`. The built CSS file is also included in the npm package.
-
-```sh
-$ npm run build
-```
+## Development
+See [DEVELOP.md](./DEVELOP.md) for development docs.
 
 ## Releasing (Staff only)
-
 You can find docs about our release process in [RELEASING.md](./RELEASING.md).
 
 ## Documentation
 
-You can read more about primer in the [docs][docs].
+Primer CSS documentation is published to the [GitHub Style Guide](https://styleguide.github.com/primer/).
 
 ## License
 
 [MIT](./LICENSE) © [GitHub](https://github.com/)
 
 [primer]: https://github.com/primer/primer
-[docs]: http://primer.github.io/
 [npm]: https://www.npmjs.com/
 [install-npm]: https://docs.npmjs.com/getting-started/installing-node
 [sass]: http://sass-lang.com/

RELEASING.md

@@ -4,21 +4,56 @@
 ### In `primer/primer`:
 
 
-1. Go through the tracking PR and make sure everything that should be merged in is merged in.
+1. Go through the tracking PR and make sure everything listed is merged in.
 
 2. To update the change log for your release, click on the details links for the continuous-integration/travis-ci/push build.  Expand the `Deploying application` output and copy the change log content. Update the [CHANGELOG.md](https://github.com/primer/primer/blob/master/CHANGELOG.md) file with the change log content from the build.
 
-3. Run the version bump in your terminal: `npm run bump`.
+3. Bump the package versions in your terminal:
 
-4. Run `script/check-versions` to double check there are no version conflicts. You may need to update peer dependencies in `primer-popover` and `primer-marketing-buttons`.
+  ```sh
+  npm run bump
+  ```
+
+4. Run `script/check-versions` to catch any cross-module version mismatches. You may need to update peer dependencies in `primer-popover` and `primer-marketing-buttons`.
 
 5. Test your changes with the latest release candidate version in the appropriate places (styleguide, storybook, github/github).
 
-6. Once the release PR is approved and you've done necessary testing, merge to `master`. This will trigger a publish to npm.
+6. Once the release PR is approved and you've done necessary testing, merge to `master`. This will trigger publishing to npm.
+
+7. Create a new release branch for the next release from `master` and name it `release-<version>`. Please use the following template for the PR description:
+
+    ```md
+    # Primer [Major|Minor|Patch] Release
+
+    Tracking Issue for next release: 📦 **0.0.0**
+    Approximate release date: 📆 DD/MM/YY
+
+    ### Must
+
+    - [ ]
+
+    ### Should
+
+    - [ ]
+
+    ### Could
+
+    - [ ]
+
+    ----
+
+    ### Ship checklist
 
-7. Create a new release branch for the next release from `master` and name it `release-<version>`.
+    - [ ] Update CHANGELOG
+    - [ ] Run version bump
+    - [ ] Update primer.github.io
+    - [ ] Update github/github
+    - [ ] Update the style guide
+    - [ ] Update the release tag note
+    - [ ] Create a new pull request for the next release
 
- (CI will publish a release candidate version to npm for branches prefixed with `release`. These version numbers have a `rc.<number>` suffix on them)
+    /cc @primer/ds-core
+    ```
 
 
 ### In `github/github`: