release: git-chglog changes with docs (#4482)

.chglog/config.yml

@@ -4,6 +4,22 @@ info:
   title: CHANGELOG
   repository_url: https://github.com/Azure/aks-engine
 options:
+  commits:
+    filters:
+      Type:
+        - build
+        - chore
+        - ci
+        - docs
+        - feat
+        - fix
+        - perf
+        - refactor
+        - revert
+        - security
+        - style
+        - test
+    sort_by: Scope
   commit_groups:
     title_maps:
       build: Build 🏭

.github/semantic.yml

@@ -0,0 +1,14 @@
+types:
+  - build
+  - chore
+  - ci
+  - docs
+  - feat
+  - fix
+  - perf
+  - refactor
+  - revert
+  - security
+  - style
+  - test
+  - release

docs/community/release-checklist.md

@@ -21,7 +21,7 @@ necessary to release a product such as AKS Engine, which depends on several exte
 AKS Engine releases new versions when the team of maintainers determine it is needed. This usually
 amounts to one or more releases each month.
 
-Minor versions—for example, v0.**64**.0—are created from the master branch whenever
+Minor versions—for example, v0.**65**.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.
 
 Patch versions—for example, v0.64.**1**—are based on the previous release and created on demand
@@ -48,37 +48,91 @@ to a patch or to a minor release will not break anything.
 
 Let's go through the process of creating a new release of the [aks-engine][] binary.
 
-We will use **v0.63.0** as an example herein. You should replace this with the new version you're releasing.
+We will use **v0.65.0** as an example herein. You should replace this with the new version you're releasing.
 
-```
+### Prepare a Release Branch
-$ export TAG=v0.63.0
-```
-### Generate Release Notes
-
-Use the [`git-chglog`][git-chglog] tool to generate release notes:
-
-```
-$ git-chglog $TAG
-```
-
-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.
-
-Save the markdown to a new file under the `releases/` directory, and name it `CHANGELOG-$TAG.md`. For example, for this release we would create a new file:
-
-- `releases/CHANGELOG-v0.63.0.md`
-
-If it is helpful to manually curate the CHANGELOG with more human readable language, please do. This will be the first thing a user encounters when evaluating whether or not to use this release. Create a PR with just the new CHANGELOG file, get it reviewed by maintainers, and ensure it is merged to the master branch.
-
-### Prepare and Tag a Branch
 
 First ensure that all the commits to be included in the release are ready in your local repository.
 
 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. Ensure that the CHANGELOG file that corresponds to this release is present in the release branch.
 
+```sh
+$ git checkout master
+Switched to branch 'master'
+Your branch is up to date with 'origin/master'.
+$ git fetch upstream
+$ git merge upstream/master
+Already up to date.
+$ export RELEASE=v0.65.0 && git checkout -b release-$RELEASE && git push upstream release-$RELEASE
+Switched to a new branch 'release-v0.65.0'
+Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
+remote:
+remote: Create a pull request for 'release-v0.65.0' on GitHub by visiting:
+remote:      https://github.com/Azure/aks-engine/pull/new/release-v0.65.0
+remote:
+To https://github.com/Azure/aks-engine.git
+ * [new branch]          release-v0.65.0 -> release-v0.65.0
+```
+
+### Generate Release Notes
+
+First, create a branch on your fork that you will use to push a release notes PR for approval by the maintainers:
+
+```sh
+$ git checkout -b CHANGELOG-$RELEASE && git push origin CHANGELOG-$RELEASE
+Switched to a new branch 'CHANGELOG-v0.65.0'
+Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
+remote:
+remote: Create a pull request for 'CHANGELOG-v0.65.0' on GitHub by visiting:
+remote:      https://github.com/jackfrancis/aks-engine/pull/new/CHANGELOG-v0.65.0
+remote:
+To https://github.com/jackfrancis/aks-engine.git
+ * [new branch]          CHANGELOG-v0.65.0 -> CHANGELOG-v0.65.0
+```
+
+Now, create a temporary local tag that correlates with the release version to allow `git-chglog` to create human-readable release notes:
+
+```sh
+$ export RELEASE=v0.65.0 && git tag $RELEASE && git-chglog --tag-filter-pattern 'v\d+\.\d+\.\d+$' --output releases/CHANGELOG-$RELEASE.md $RELEASE && git tag -d $RELEASE
+```
+
+You may now review the generated release notes, and possibly add some manual curation if appropriate. After the CHANGELOG looks good, push the changes to your fork + branch:
+
+```sh
+$ git add releases/CHANGELOG-$RELEASE.md
+$ git commit -m "release: $RELEASE CHANGELOG"
+[CHANGELOG-v0.65.0 f8d86fbdb] release: v0.65.0 CHANGELOG
+ 1 file changed, 31 insertions(+)
+ create mode 100644 releases/CHANGELOG-v0.65.0.md
+$ git push --set-upstream origin CHANGELOG-$RELEASE
+Enumerating objects: 6, done.
+Counting objects: 100% (6/6), done.
+Delta compression using up to 8 threads
+Compressing objects: 100% (4/4), done.
+Writing objects: 100% (4/4), 1000 bytes | 111.00 KiB/s, done.
+Total 4 (delta 2), reused 0 (delta 0), pack-reused 0
+remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
+To https://github.com/jackfrancis/aks-engine.git
+   e6ca055c4..f8d86fbdb  CHANGELOG-v0.65.0 -> CHANGELOG-v0.65.0
+Branch 'CHANGELOG-v0.65.0' set up to track remote branch 'CHANGELOG-v0.65.0' from 'origin'.
+```
+
+And now create a PR and get a couple maintainers to review and lgtm.
+
+### Add CHANGELOG to release branch
+
+After the CHANGELOG PR merges, you now want to add it to your release branch to enable the automated release CI to progress.
+
+```
+$ git checkout release-$RELEASE
+Switched to branch 'release-v0.65.0'
+$ git cherry-pick <commit SHA of CHANGELOG commit in master branch>
+```
+
 Tag the release commit and push it to GitHub:
 
 ```
-$ git tag $TAG && git push upstream $TAG
+$ git tag $RELEASE && git push upstream $RELEASE
 ```
 
 ### Automated Release CI
@@ -94,7 +148,7 @@ Finally, let's make the new aks-engine release easy to install.
 Create a pull request to add the new release to [brew][] through our [homebrew tap repository][brew-tap]. Update the macOS sha256 checksum with this command:
 
 ```
-$ shasum -a 256  _dist/aks-engine-$TAG-darwin-amd64.tar.gz
+$ shasum -a 256  _dist/aks-engine-$RELEASE-darwin-amd64.tar.gz
 ```
 
 The PR will look very similar to [this one][brew-pr].