docs: how to create a new aks-engine release (#829)

docs/community/release-checklist.md

@@ -3,7 +3,7 @@
 aks-engine uses a [continuous delivery][] approach for creating releases. Every merged commit that passes
 testing results in a deliverable that can be given a [semantic version][] tag and shipped.
 
-## Release as Needed
+## Master Is Always Releasable
 
 The master `git` branch of a project should always work. Only changes considered ready to be
 released publicly are merged.
@@ -12,25 +12,26 @@ aks-engine depends on components that release new versions as often as needed. F
 a high priority bug requires the project maintainer to create a new patch release.
 Merging a backward-compatible feature implies a minor release.
 
-By releasing often, each component release becomes a safe and routine event. This makes it faster
+By releasing often, each release becomes a safe and routine event. This makes it faster
 and easier for users to obtain specific fixes. Continuous delivery also reduces the work
 necessary to release a product such as aks-engine, which depends on several external projects.
 
 "Components" applies not just to AKS projects, but also to development and release
-tools, orchestrator versions (Kubernetes, DC/OS, Swarm),to Docker base images, and to other Azure
+tools, to orchestrator versions, to Docker base images, and to other Azure
 projects that do [semantic version][] releases.
 
-## aks-engine Releases Each Month
+## AKS Engine Releases As Needed
 
-aks-engine has a regular, public release cadence. From v0.1.0 onward, new aks-engine feature
-releases arrive on the first Thursday of each month. Patch releases are created at any time,
-as needed. GitHub milestones are used to communicate the content and timing of major and minor
-releases, and longer-term planning is visible at [the Roadmap](planning-process.md#open-roadmap).
+AKS Engine releases new versions when the team of maintainers determine it is needed. This usually
+amounts to one or more releases each month.
 
-aks-engine release timing is not linked to specific features. If a feature is merged before the
-release date, it is included in the next release.
+Minor versions—for example, v0.**32**.0—are created from the master branch whenever
+important features or changes have been merged and CI testing shows it to be stable over time.
 
-See "[How to Release aks-engine](#how-to-release-aks-engine)" for more detail.
+Patch versions—for example, v0.32.**3**—are based on the previous release and created on demand
+whenever important bug fixes arrive.
+
+See "[Creating a New Release](#creating-a-new-release)" for more detail.
 
 ## Semantic Versioning
 
@@ -47,54 +48,107 @@ In general, changes to anything a user might reasonably link to, customize, or i
 be backward-compatible, or else require a major release. aks-engine users can be confident that upgrading
 to a patch or to a minor release will not break anything.
 
-## How to Release aks-engine
+## Creating a New Release
 
-This section leads a maintainer through creating an aks-engine release.
+Let's go through the process of creating a new release of [aks-engine][].
 
-### Step 1: Assemble Master Changelog
+We will use **v0.32.3** as an example herein. You should replace this with the new version you're releasing.
 
-A change log is a file which contains a curated, chronologically ordered list of changes
-for each version of aks-engine, which helps users and contributors see what notable changes
-have been made between each version of the project.
+```
+$ export TAG=v0.32.3
+```
 
-The CHANGELOG should be driven by release milestones defined on Github, which track specific deliverables and
-work-in-progress.
+### Prepare and Tag a Branch
 
-### Step 2: Manual Testing
+First ensure that all the commits to be included in the release are ready in your local repository.
 
-Now it's time to go above and beyond current CI tests. Create a testing matrix spreadsheet (copying
-from the previous document is a good start) and sign up testers to cover all permutations.
+For a major or minor release, create a branch from master. For a patch, create a branch from the previous release tag and use `git cherry-pick` to apply specific commits.
 
-Testers should pay special attention to the overall user experience, make sure upgrading from
-earlier versions is smooth, and cover various storage configurations and Kubernetes versions and
-infrastructure providers.
+Tag the release commit and push it to GitHub:
 
-When showstopper-level bugs are found, the process is as follows:
+```
+$ git tag $TAG && git push upstream $TAG
+```
 
-1. Create an issue that describes the bug.
-1. Create an PR that fixes the bug. PRs should always include tests (unit or e2e as appropriate) to add automated coverage for the bug.
-1. Once the PR passes and is reviewed, merge it and update the CHANGELOG
+### Generate Release Notes
 
-### Step 3: Tag and Create a Release
+Use the [`git-chglog`][git-chglog] tool to generate release notes:
 
-TBD
+```
+$ git-chglog $TAG
+```
 
-### Step 4: Close GitHub Milestones
+Be sure to proofread the output and verify that the intended commits appear. If a commit made it to master that didn't have a [conventional commit message][conventional-commit], you'll need to add it to the appropriate section by hand.
 
-TBD
+Save the markdown that it prints so it can be pasted into the GitHub release.
 
-### Step 5: Let Everyone Know
+### Generate Download Artifacts
 
-Let the rest of the team know they can start blogging and tweeting about the new aks-engine release.
-Post a message to the #company channel on Slack. Include a link to the released chart and to the
-master CHANGELOG:
+Make sure your repository has no local changes, then build the aks-engine distribution archives:
 
-```text
-@here aks-engine 0.1.0 is here!
-Master CHANGELOG: https://github.com/Azure/aks-engine/CHANGELOG.md
 ```
+$ git status -s --untracked-files=no  # check for local changes
+$ git clean -fdx && make clean dist
+```
+
+When this finishes, the `_dist` directory will be populated with three .zip and three .tar.gz archive files.
+
+### Make a GitHub Release
+
+Now navigate to the aks-engine project on GitHub and start a [new release][new-release]:
+
+![draft_new_release.png](../static/img/draft_new_release.png)
+
+Select the tag we pushed previously, and use that tag as the release title. Then paste the release notes from the previous step into the big text field:
+
+![release_notes.png](../static/img/release_notes.png)
+
+Finally, drag all six archive files we created with `make dist` into the "Attach binaries" field at the bottom of the release web form:
+
+![attach_archives.png](../static/img/attach_archives.png)
+
+Proofread the release notes and satisfy yourself that everything is in order. Click the "Publish release" button when the new aks-engine release is ready for the world.
+
+### Update Package Managers
+
+Finally, let's make the new aks-engine release easy to install.
+
+#### The `gofish` package manager
+
+Create a pull request to add the new release to [gofish][] through the [fish-food repository][gofish-food]. You will need to calculate the sha256 checksum for each of the .tar.gz archives:
+
+```
+$ shasum -a 256 _dist/aks-engine-$TAG-darwin-amd64.tar.gz  # macOS example
+250c0b645ad22514f4af52393ebcda95f1f911032274801f17c295800741f75b  _dist/aks-engine-v0.32.3-darwin-amd64.tar.gz
+```
+
+Paste each checksum in the appropriate section and update the release version. The PR will look very similar to [this recent update][gofish-pr].
+
+#### The `brew` package manager
+
+Create a pull request to add the new release to [brew][] through our [homebrew tap repository][brew-tap]. Use the macOS sha256 checksum from the `gofish` PR in the previous step. The PR will look very similar to [this recent update][brew-pr].
+
+#### The `choco` package manager
+
+Adding new versions to [choco][] is automated, but you can check the status of package approval and publishing at the [aks-engine chocolatey page][choco-status].
+
+Note that it can take a while for the NuGet machinery to submit the current release, and it may be reviewed for several days before it is actually made available.
+
+#### The official Docker image
 
-You're done with the release. Nice job!
+(Coming soon).
 
+[aks-engine]: https://github.com/Azure/aks-engine/releases
+[brew]: https://brew.sh/
+[brew-pr]: https://github.com/Azure/homebrew-aks-engine/pull/5
+[brew-tap]: https://github.com/Azure/homebrew-aks-engine/
+[choco]: https://chocolatey.org/
+[choco-status]: https://chocolatey.org/packages/aks-engine/
+[conventional-commit]: https://www.conventionalcommits.org/en/v1.0.0-beta.3/
+[git-chglog]: https://github.com/git-chglog/git-chglog
+[gofish]: https://github.com/fishworks/gofish
+[gofish-food]: https://github.com/fishworks/fish-food/
+[gofish-pr]: https://github.com/fishworks/fish-food/pull/141
+[new-release]: https://github.com/Azure/aks-engine/releases/new
 [continuous delivery]: https://en.wikipedia.org/wiki/Continuous_delivery
 [semantic version]: http://semver.org