Update documentation to reflect new release process

docs/release.md

@@ -7,12 +7,12 @@ Mayflower release managers with the necessary repo permissions can follow these
 1. Check out the [massgov/mayflower `dev` branch](https://github.com/massgov/mayflower/commits/dev): `git checkout dev` and pull the latest from upstream `git pull upstream dev`. (This assumes that your massgov/mayflower remote repo is named `upstream`)
 1. Create a release branch `git checkout -b release-#.#.#` where `#.#.#` is the next version (i.e. `5.0.0`).  Read more about [Mayflower and semantic versioning](docs/versioning.md) to ensure that your are creating the right type of version.
 1. Add [release notes](https://github.com/massgov/mayflower/blob/dev/docs/change-log-instructions.md) to the top of [release notes](/release-notes.md) based on the "changelog.txt" files, remove all the "changelog.txt" files and then commit.
-1. Move into the `stylguide` directory `cd styleguide` (may be a good idea to run `npm install` in case the release includes new packages).
-1. Bump the version of the npm package by running `gulp bump -v=#.#.#` where `#.#.#` is the version you are releasing.
+1. Move into the `styleguide` directory `cd styleguide` and run `npm install` in case the release includes new packages.
+1. Update the version of the npm package by editing the `version` field in `package.json`.
 1. Commit your version bump file update.
 1. Push release branch to `massgov/mayflower` (i.e. `git push upstream release-#.#.#`).
 1. Wait for [the circle build](https://circleci.com/gh/massgov/mayflower) to pass, which will deploy your release branch to staging automagically :).
-1. Verify release notes against the site rendered at: `https://mayflower.digital.mass.gov/<your-release-branch>/index.html`.
+1. Verify release notes against the site rendered at: `https://mayflower.digital.mass.gov/b/<your-release-branch>/index.html`.
 1. Smoke test Mayflower (a quick way to do this is to browse around to some of the different pages in the "pages" menu and do a quick gut check)
 1. Open a Github Pull Request to merge (no squash!) the release branch into the `master` branch.
     1. Add the relevant release notes to the PR notes.
@@ -23,23 +23,9 @@ Mayflower release managers with the necessary repo permissions can follow these
     1. Release title: `#.#.#` (your release number)
     1. Describe the release: paste your release notes markdown here, after the release version/date line, add a link to the release PR (protip: type `#` and you'll get an autocomplete dropdown to get to your pr)
 1. Wait for [the circle builds](https://circleci.com/gh/massgov/mayflower) to pass
-1. Pull down master `git pull upstream master`
-1. Check out master `git checkout master`
-1. Pull down your tag `git fetch --tags`
-1. Make sure you are in `styleguide` (cd into `styleguide` if you're not)
-1. Make sure you are have the necessary credentials for the s3 bucket and npm:
-    1. In order to push to the mayflower s3 bucket, you need to have credentials set up in `<mayflower>/styleguide/tools/gulp/local.js` (you can copy `local.js.example` as a model).  Ask a team member for help with credentials.
-    1. In order to push the Mayflower package to [NPM](https://npmjs.com/@massds/mayflower), you need to be authenticated on NPM, by one of the following:
-        1. Having an `.npmrc` file with credentials for the `@massds` account (or your own NPM account if you're added to the Mayflower package as an owner) in the styleguide directory of your Mayflower repo (this file is not and should not be versioned -- ask a team member for credentials)
-            - See [npmjs docs re: .npmrc](https://docs.npmjs.com/files/npmrc#per-project-config-file\n\n2)
-        1. Having an `NPM_TOKEN` environment variable for `@massds`
-            - See [npmjs docs re: NPM_TOKEN](http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules)
-        1. Authenticating from the npm CLI (Note: you must be added to the Mayflower NPM package project as an owner -- ask a team member for help)
-            - See [npmjs docs](https://docs.npmjs.com/getting-started/publishing-npm-packages#preparation)
-1. Deploy the release (to its three locations: prod `/`, current version `/<your-tag-name>/`, and latest minor `/<current-major-version>/`) and publish the [@massds/mayflower package on NPM](https://www.npmjs.com/package/@massds/mayflower) by running `../scripts/deploy-mayflower.sh -b <your-tag-name>` and follow the prompts.
 1. Smoke test [Prod](http://mayflower.digital.mass.gov)
     - Make sure the home page reflects the date and version
-1. Open a GitHub Pull Request to merge `master` into `develop` (this should only bring an updated `release-notes.md`, `@pages/readme2.json`). If a feature was reverted on the release branch, have a peer do the merge after a review.
+1. Open a GitHub Pull Request to merge `master` into `dev` (this should only bring an updated `release-notes.md`, `package.json`). If a feature was reverted on the release branch, have a peer do the merge after a review.
 1. In JIRA Go to the [DP project](https://jira.state.ma.us/projects/DP/).
     1. Click on the Releases icon on the left side (it looks like a boat/ship).
     1. Add a new release version with today's date.
@@ -53,9 +39,6 @@ In the event that a release needs to be rolled back from production, follow thes
 
 1. Pull down and checkout the prior release tag and check it out by running `git pull --tags` then `git checkout <prior-release-tag>` (*Note: you should see a message from git that you are in a [detached head state](https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit) and that is okay.*)
 1. Make sure you are in `/styleguide` directory
-1. Deploy prior release tag to:
-    1. [Prod](http://mayflower.digital.mass.gov) by running `../scripts/deploy-prod-s3.sh -b <prior-release-tag>`
-        1. When prompted, confirm your prod deployment by typing: `y`
-    1. Latest minor by running `../scripts/deploy-latest-minor-s3.sh -b <prior-release-tag>`
-        1. When prompted, confirm your latest minor deployment by typing: `y`
+1. Deploy prior release tag to S3 (note: you must have the S3 credentials to do this):
+    1. `gulp patternlab:release`
 1. Validate rollback by browsing to [Prod](http://mayflower.digital.mass.gov) as well as `https://mayflower.digital.mass.gov/<current-major>/` and verifying that the home page reflects the correct version

docs/s3-architecture.md

@@ -9,8 +9,7 @@ We host Mayflower (i.e. the static output of a Pattern Lab “build”) in an am
 |Name|URL path|Example|Purpose|What code gets deployed here?|When does code get deployed here?|How does code get deployed here?|Permanent or temporary?|
 |---|---|---|---|---|---|---|---|
 |**Production**|/|mayflower.digital.mass.gov/|The latest and greatest version of Mayflower.  Mostly used for browsing and (soon) implementation documentation from the home page.|Pattern Lab build artifacts from a production tag (i.e. 5.10.0) cut off master branch..|During the release process, when a release branch is merged into master.|Release manager executes a script command.  See release docs.|Permanent (and dynamic, i.e. the contents change when a new release is deployed here)|
-|**Latest minor**|/<current-major-#>/|/5/|The latest minor version within a given major: implementers who link to these css/js/font/icon assets get safe updates automatically|Pattern Lab build artifacts from a production tag (i.e. 5.10.0) cut off master branch. Note: if the production tag starts a new major release, then a new /<current-major-#> directory will be created automatically.|During the release process, when a release branch is merged into master.|Release manager executes a script command.  See release docs.|Permanent (and dynamic, i.e. the contents change when a new release is deployed here)|
-|**Release**|/<#.#.#>/|/5.10.0/|Static snapshot of a given release: implementers who link to these css/js/font/icon assets get updates only when they manually change their links to the next version|Pattern Lab build artifacts from a production tag (i.e. 5.10.0) cut off master branch..|During the release process, when a release branch is merged into master.|Release manager executes a script command.  See release docs.|Permanent (and static, i.e. once is a release is deployed here it will never change)|
-|**Staging**|/release-#.#.#/|/release-5.11.0/|A given release branch; used to stage an upcoming release for functional / integration testing.|Pattern Lab build artifacts from the release branch.|When a release branch (which has an open PR) has a new commit pushed.|CircleCI deploys as part of build for the release branch.|Temporary (can be deleted when the release testing is done) @TODO script this|
-|**Dev**|/dev/|/dev/|Bleeding edge of our codebase; used for browsing all of the code that has been merged into dev branch prior to release.|Pattern Lab build artifacts from the dev branch. |When a feature PR is squashed and merged into dev branch.|CircleCI deploys as part of build for the  dev branch.|Permanent (and dynamic, i.e. the contents change when new work is merged in)|
-|**Feature branch**|/<my-branch-name>/|/DP-1234-my-ticket/|The feature development done on a particular branch; used for internal and external review functional tests.|Pattern Lab build artifacts from the feature branch.|When a feature branch (which has an open PR) has a new commit pushed.|CircleCI deploys as part of build for the feature branch.|Temporary (can be deleted when the feature testing is done) @TODO script this
+|**Latest minor**|/v/<current-major-#>/|/v/5/|The latest minor version within a given major: implementers who link to these css/js/font/icon assets get safe updates automatically|Pattern Lab build artifacts from a production tag (i.e. 5.10.0) cut off master branch. Note: if the production tag starts a new major release, then a new /<current-major-#> directory will be created automatically.|During the release process, when a release branch is merged into master.|Release manager executes a script command.  See release docs.|Permanent (and dynamic, i.e. the contents change when a new release is deployed here)|
+|**Staging**|/b/release-#.#.#/|/b/release-5.11.0/|A given release branch; used to stage an upcoming release for functional / integration testing.|Pattern Lab build artifacts from the release branch.|When a release branch (which has an open PR) has a new commit pushed.|CircleCI deploys as part of build for the release branch.|Temporary (can be deleted when the release testing is done) @TODO script this|
+|**Dev**|/b/dev/|/b/dev/|Bleeding edge of our codebase; used for browsing all of the code that has been merged into dev branch prior to release.|Pattern Lab build artifacts from the dev branch. |When a feature PR is squashed and merged into dev branch.|CircleCI deploys as part of build for the  dev branch.|Permanent (and dynamic, i.e. the contents change when new work is merged in)|
+|**Feature branch**|/b/<my-branch-name>/|/b/DP-1234-my-ticket/|The feature development done on a particular branch; used for internal and external review functional tests.|Pattern Lab build artifacts from the feature branch.|When a feature branch (which has an open PR) has a new commit pushed.|CircleCI deploys as part of build for the feature branch.|Temporary (can be deleted when the feature testing is done) @TODO script this

styleguide/readme-gulp.md

@@ -1,17 +1,29 @@
 ## README IN PROGRESS
 
 ### Gulp
-See [gulp-readme.md](./gulp-advanced/tools/gulp/gulp-readme.md) for setup.
 
-The entry `gulpfile.js` is located in `tools/gulp` and all gulp commands need to be run from this directory. There is also a proxy `gulpfile.js` at the project root, which can run all the same commands.
+Available Commands:
 
-Available commands are
- * `gulp` or `gulp dev`- will run dev build with watchers
- * `gulp build` - will run dev _without_ watchers.
- * `gulp prod` - will run production build without watchers
- * `gulp [task]` - where task is loaded in `gulpfile.js`.  eg. `css`, `svg-sprite`
+#### Pattern Lab
+* `patternlab:build` - Compile Pattern Lab into `styleguide/public`
+* `patternlab:watch` - Compile and start a live development server.
+* `patternlab:publish` - Compile and deploy to the S3 bucket at /b/${BRANCH}.
+* `patternlab:release` - Compile and deploy to the S3 bucket at /b/${BRANCH}.  If tagged, and tag is not a pre-release tag, also deploys to /v/${MAJOR_VERSION}, and /.
 
-The watcher will also start a [browserSync](https://browsersync.io/) server.  The console will tell you the exact port, but it usually runs on [http://localhost:3000/](http://localhost:3000/).  
+#### Artifacts
+* `artifacts:build` - Clones artifact repo, cleans it, and builds assets into `styleguide/artifacts`
+* `artifacts:publish` - Runs `artifacts:build`, then pushes to `$BRANCH` on the artifacts repository.
+* `artifacts:release` - Runs `artifacts:build`, then pushes to `$BRANCH` and `$TAG` on the artifacts repository.
+
+#### NPM
+* `npm:build` - Builds the NPM package to `styleguide/npm`.
+* `npm:release` - Runs `npm:build` and then publishes to the NPM registry.
+
+### Generic:
+* `default` - Alias for `patternlab:watch`
+* `prod` - Alias for `patternlab:build`
+
+During the `default` or `watch` tasks, the watcher will also start a [browserSync](https://browsersync.io/) server.  The console will tell you the exact port, but it usually runs on [http://localhost:3000/](http://localhost:3000/).
 
 ### CSS
 All css source files are located in `/assets/scss/`.  Gulp will compile all scss files in this directory and concat them into a single file `/assets/build/css/index-generated.css`.