From 6d23e0913c53e9ab549a66efd1f73f2862877f10 Mon Sep 17 00:00:00 2001
From: Pat Cavit <github@patcavit.com>
Date: Thu, 6 Apr 2017 20:41:55 +0000
Subject: [PATCH] docs: try to improve releasing docs

---
 docs/releasing.md | 77 ++++++++++++++++++++++++++---------------------
 1 file changed, 42 insertions(+), 35 deletions(-)

diff --git a/docs/releasing.md b/docs/releasing.md
index 12ceb19b..7a9cbe3c 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -1,49 +1,56 @@
-# Releasing
+# Mithril Release Processes
 
-## Publishing to NPM
+## Releasing a new Mithril version
 
-Releasing new builds of mithril to NPM is mostly automated via `npm run release`
+### Prepare the release
 
-1. Update information in `docs/change-log.md` to match reality & the new version that will be released
-2. `npm run release <major|minor|patch|semver>`
+1. Determine patch level of the change
+2. Update information in `docs/change-log.md` to match reality & the new version that will be released
 
-All further steps are automated and run as follows:
+### Merge from `next` to `master`
 
-3. New bundles are generated using updated version
-4. Tests are run
-5. Linting is run (but doesn't fail build)
-6. Version number in package.json is incremented
-7. `git add` called on bundle output
-8. `package.json` and updated bundles are committed to git
-9. previous commit is tagged using new version number
-10. `git push --follow-tags` pushes up new version commit & tag to github
-11. Travis sees new release, starts build
-12. Travis generates new bundles before running tests
-13. Travis runs tests
-14. Travis lints files (but can't fail build)
-15. If build fails, abort
-16. Build succeeded, so travis will commit back any changes to the repo (but there won't be any)
-17. Travis sees that this commit has a tag associated with it
-18. Travis will use the encrypted npm creds in `.travis.yml` to publish a new version to npm
+3. Switch to `master` and merge `next` on top of it
 
-## Publishing a GitHub release
+```bash
+$ git co master
+$ git merge next
+```
 
-Happens automatically as part of the [Publishing to NPM](#publishing-to-npm) process described above.
+4. Clean & update npm dependencies and ensure the tests are passing.
 
-Does require a manual description to be added though, as the auto-generated one isn't very interesting. I suggest coming up with a fun title & then copying the `docs/change-log.md` entry for the build.
+```bash
+$ npm prune
+$ npm i
+$ npm test
+```
 
-## Updating `docs/change-log.md`
+### Publish the release
 
-This is still a manual process, I'm sorry.
+5. `npm run release <major|minor|patch|semver>`, see the docs for [`npm version`](https://docs.npmjs.com/cli/version)
+6. Travis will push the new release to npm & create a GitHub release
 
-## Updating docs (outside of a new version)
+### Update the GitHub release
+
+7. The GitHub Release will require a manual description & title to be added. I suggest coming up with a fun title & then copying the `docs/change-log.md` entry for the build.
+
+## Updating mithril.js.org
 
 Fixes to documentation can land whenever, updates to the site are published via Travis.
 
-1. `git co next`
-2. `git pull lhorie next`
-3. `git co master`
-4. `git co next -- ./docs`
-5. Ensure that no new features are added
-6. `git push lhorie`
-7. After the Travis build completes new docs should appear in ~3 minutes
+```bash
+# These steps assume that lhorie/mithril.js is a git remote named "lhorie"
+
+# Ensure your next branch is up to date
+$ git co next
+$ git pull lhorie next
+
+# Splat the docs folder from next onto master
+$ git co master
+$ git co next -- ./docs
+
+# Manually ensure that no new feature docs were added
+
+$ git push lhorie
+```
+
+After the Travis build completes the updated docs should appear on https://mithril.js.org in a few minutes.