From 09f31057b8f49d5f739b1f4fa06f6caa0f5f7415 Mon Sep 17 00:00:00 2001 From: Jack Francis Date: Thu, 24 Jun 2021 09:53:16 -0700 Subject: [PATCH] release: git-chglog changes with docs (#4482) --- .chglog/config.yml | 16 +++++ .github/semantic.yml | 14 ++++ docs/community/release-checklist.md | 102 +++++++++++++++++++++------- 3 files changed, 108 insertions(+), 24 deletions(-) create mode 100644 .github/semantic.yml diff --git a/.chglog/config.yml b/.chglog/config.yml index a4cd693da..3f6f9954e 100755 --- a/.chglog/config.yml +++ b/.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 🏭 diff --git a/.github/semantic.yml b/.github/semantic.yml new file mode 100644 index 000000000..7c5a00c70 --- /dev/null +++ b/.github/semantic.yml @@ -0,0 +1,14 @@ +types: + - build + - chore + - ci + - docs + - feat + - fix + - perf + - refactor + - revert + - security + - style + - test + - release diff --git a/docs/community/release-checklist.md b/docs/community/release-checklist.md index 4a2a41b15..b850dc513 100644 --- a/docs/community/release-checklist.md +++ b/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. -``` -$ 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 +### Prepare a Release 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 +``` + 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].