From 9044411c2fcf7f6e18f47793011c4e707788466b Mon Sep 17 00:00:00 2001 From: Teemu Rytilahti Date: Wed, 22 May 2024 19:03:48 +0200 Subject: [PATCH 1/3] Update release playbook --- RELEASING.md | 56 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 96212b1e9..6349db797 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,4 +1,4 @@ -1. Set release information +## Set release information ```bash # export PREVIOUS_RELEASE=$(git describe --abbrev=0) @@ -6,13 +6,23 @@ export PREVIOUS_RELEASE=0.3.5 # generate the full changelog since last pyhs100 r export NEW_RELEASE=0.4.0.dev4 ``` -2. Update the version number +## Update the version number ```bash poetry version $NEW_RELEASE ``` -3. Write a short and understandable summary for the release. +## Update dependencies and run tests + +```bash + +poetry update +pre-commit run --all-files && pytest kasa +``` + +## Write a short and understandable summary for the release. + +This step is only needed, if you want to include a summary text in the autogenerated changelog. * Create a new issue and label it with release-summary * Create $NEW_RELEASE milestone in github, and assign the issue to that @@ -24,20 +34,22 @@ poetry version $NEW_RELEASE # gem install github_changelog_generator --pre # https://github.com/github-changelog-generator/github-changelog-generator#github-token export CHANGELOG_GITHUB_TOKEN=token -github_changelog_generator --base HISTORY.md --user python-kasa --project python-kasa --since-tag $PREVIOUS_RELEASE --future-release $NEW_RELEASE -o CHANGELOG.md --exclude-tags-regex 'dev\d$' +github_changelog_generator --base HISTORY.md --user python-kasa --project python-kasa --since-tag $PREVIOUS_RELEASE --future-release $NEW_RELEASE -o CHANGELOG.md + + +#-exclude-tags-regex 'dev\d$' ``` Remove '--exclude-tags-regex' for dev releases. +TODO: Find a nice way to collate dev* changes to real releases. Excluding them causes them to re-appear for pre-releases, but maybe that's fine? -4. Commit the changed files +## Commit the changed files ```bash -git commit -av +git commit --all --verbose ``` -5. Create a PR for the release. - -6. Get it merged, fetch the upstream master +## Create a PR for the release, merge it, and re-fetch the master ```bash git checkout master @@ -45,13 +57,31 @@ git fetch upstream git rebase upstream/master ``` -7. Tag the release (add short changelog as a tag commit message), push the tag to git +## Create a release tag + +Note, add changelog as the tag commit message so `gh release create --notes-from-tag` can be used to create a release draft. ```bash -git tag -a $NEW_RELEASE +git tag --annotate $NEW_RELEASE git push upstream $NEW_RELEASE ``` -All tags on master branch will trigger a new release on pypi. -8. Click the "Draft a new release" button on github, select the new tag and copy & paste the changelog into the description. +## Create release using 'gh release create' + +### Pre-releases + +```bash +gh release create $NEW_VERSION --verify-tag --latest=false --notes-from-tag --prerelease --draft +``` + +### Release + +```bash +gh release create $NEW_VERSION --verify-tag --latest=true --notes-from-tag --draft +``` + + +## Manual releasing + +Go to the linked URL, verify the contents, and click "release" button to trigger the release CI. From b6273509280fda485712c025892eedba97137f82 Mon Sep 17 00:00:00 2001 From: sdb9696 Date: Wed, 5 Jun 2024 13:45:56 +0100 Subject: [PATCH 2/3] Update releasing runbook --- .github_changelog_generator | 1 + RELEASING.md | 180 ++++++++++++++++++++++++++++++------ 2 files changed, 151 insertions(+), 30 deletions(-) diff --git a/.github_changelog_generator b/.github_changelog_generator index 0341d4088..8a6b1c763 100644 --- a/.github_changelog_generator +++ b/.github_changelog_generator @@ -2,3 +2,4 @@ breaking_labels=breaking change add-sections={"docs":{"prefix":"**Documentation updates:**","labels":["documentation"]}} release_branch=master usernames-as-github-logins=true +exclude-labels=duplicate,question,invalid,wontfix,release-prep diff --git a/RELEASING.md b/RELEASING.md index 6349db797..28b8daa3f 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,9 +1,62 @@ +## Install Github CLI + +Install to use the command lines below. + +Alternatively can use the github website but ensure you follow the all the --labels --titles etc in the `gh` command lines below. + +https://github.com/cli/cli#installation + +For rpi: + +```bash +sudo apt update +sudo apt install gh +``` + +## Install github_changelog_generator + +If not already installed + +github_changelog_generator requires Ruby to be installed. +Instructions vary based on OS. For rpi: + +```bash +sudo apt-get install rbenv +sudo apt-get install ruby-dev +sudo gem install github_changelog_generator +``` + +## Get a githubtoken + +Or refresh an existing token + +This allows the generator to access github.com + +visit https://github.com/github-changelog-generator/github-changelog-generator#github-token + +```bash +export CHANGELOG_GITHUB_TOKEN=token +``` + ## Set release information +Replace 0.7.0.dev2 with intended new version number + +0.3.5 should always be the previous release as it's the last pyhs100 release in HISTORY.md which is the changelog prior to github release notes. + +```bash +export NEW_RELEASE=0.7.0.dev2 +export PREVIOUS_RELEASE=0.3.5 + +``` + +## Create a branch for the release + ```bash -# export PREVIOUS_RELEASE=$(git describe --abbrev=0) -export PREVIOUS_RELEASE=0.3.5 # generate the full changelog since last pyhs100 release -export NEW_RELEASE=0.4.0.dev4 +git checkout master +git fetch upstream master +git rebase upstream/master +git checkout -b release/$NEW_RELEASE ``` ## Update the version number @@ -12,76 +65,143 @@ export NEW_RELEASE=0.4.0.dev4 poetry version $NEW_RELEASE ``` -## Update dependencies and run tests +## Update dependencies ```bash +poetry install --all-extras --sync +``` + +If you want to update all dependencies to latest: +```bash poetry update -pre-commit run --all-files && pytest kasa ``` -## Write a short and understandable summary for the release. +## Run pre-commit and tests + +```bash +pre-commit run --all-files +pytest kasa +``` + +## Create release summary + +Skip this step for dev releases + +Write a short and understandable summary for the release. Can include images. -This step is only needed, if you want to include a summary text in the autogenerated changelog. +### Create $NEW_RELEASE milestone in github -* Create a new issue and label it with release-summary -* Create $NEW_RELEASE milestone in github, and assign the issue to that -* Close the issue +If not already created -3. Generate changelog +### Create new issue linked to the milestone ```bash -# gem install github_changelog_generator --pre -# https://github.com/github-changelog-generator/github-changelog-generator#github-token -export CHANGELOG_GITHUB_TOKEN=token -github_changelog_generator --base HISTORY.md --user python-kasa --project python-kasa --since-tag $PREVIOUS_RELEASE --future-release $NEW_RELEASE -o CHANGELOG.md +gh issue create --label "release-summary" --milestone $NEW_RELEASE --title "$NEW_RELEASE Release Summary" --body "Some summary text" +``` + +You can exclude the --body option to get an interactive editor or leave blank and go into the issue on github and edit there. + +### Close the issue + +Either via github or: + +```bash +gh issue close ISSUE_NUMBER +``` + +## Generate changelog + +### For pre-release +EXCLUDE_TAGS will exclude all dev tags except for the current release dev tags. -#-exclude-tags-regex 'dev\d$' +Regex should be something like this `^((?!0\.7\.0)(.*dev\d))+`. The first match group negative matches on the current release and the second matches on releases ending with dev. + +```bash +EXCLUDE_TAGS=${NEW_RELEASE%.dev*}; EXCLUDE_TAGS=${EXCLUDE_TAGS//"."/"\."}; EXCLUDE_TAGS="^((?!"$EXCLUDE_TAGS")(.*dev\d))+" +github_changelog_generator --base HISTORY.md --user python-kasa --project python-kasa --since-tag $PREVIOUS_RELEASE --future-release $NEW_RELEASE -o CHANGELOG.md --exclude-tags-regex "$EXCLUDE_TAGS" +``` + +### For production + +```bash +github_changelog_generator --base HISTORY.md --user python-kasa --project python-kasa --since-tag $PREVIOUS_RELEASE --future-release $NEW_RELEASE -o CHANGELOG.md --exclude-tags-regex 'dev\d$' ``` -Remove '--exclude-tags-regex' for dev releases. -TODO: Find a nice way to collate dev* changes to real releases. Excluding them causes them to re-appear for pre-releases, but maybe that's fine? +You can ignore warnings about missing PR commits like below as these relate to PRs to branches other than master: +``` +Warning: PR 908 merge commit was not found in the release branch or tagged git history and no rebased SHA comment was found +``` -## Commit the changed files + +## Export new release notes to variable ```bash -git commit --all --verbose +export RELEASE_NOTES=$(grep -Poz '(?<=\# Changelog\n\n)(.|\n)+?(?=\#\#)' CHANGELOG.md | tr '\0' '\n' ) +echo "$RELEASE_NOTES" +``` + +Check the release notes output and if it doesn't look right or the command doesn't work just copy paste from CHANGELOG.md for the latest release: + +```bash +export RELEASE_NOTES="paste release notes from CHANGELOG.md here" +``` + +## Commit and push the changed files + +```bash +git commit --all --verbose -m "Prepare $NEW_RELEASE" +git push upstream release/$NEW_RELEASE -u ``` ## Create a PR for the release, merge it, and re-fetch the master +### Create the PR +``` +gh pr create --title "Prepare $NEW_RELEASE" --body "$RELEASE_NOTES" --label release-prep --base master +``` + +### Merge the PR once the CI passes + +Create a squash commit and add the markdown from the PR description to the commit description. + +```bash +gh pr merge --squash --body "$RELEASE_NOTES" +``` + +### Rebase local master + ```bash git checkout master -git fetch upstream +git fetch upstream master git rebase upstream/master ``` ## Create a release tag -Note, add changelog as the tag commit message so `gh release create --notes-from-tag` can be used to create a release draft. +Note, add changelog release notes as the tag commit message so `gh release create --notes-from-tag` can be used to create a release draft. ```bash -git tag --annotate $NEW_RELEASE +git tag --annotate $NEW_RELEASE -m "$RELEASE_NOTES" git push upstream $NEW_RELEASE ``` - -## Create release using 'gh release create' +## Create release ### Pre-releases ```bash -gh release create $NEW_VERSION --verify-tag --latest=false --notes-from-tag --prerelease --draft +gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=false --prerelease + ``` -### Release +### Production release ```bash -gh release create $NEW_VERSION --verify-tag --latest=true --notes-from-tag --draft +gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=true ``` - -## Manual releasing +## Manually publish the release Go to the linked URL, verify the contents, and click "release" button to trigger the release CI. From ef4cdfeb9548e68d8c050c2cde012ca07d9a03bf Mon Sep 17 00:00:00 2001 From: sdb9696 Date: Wed, 5 Jun 2024 16:04:24 +0100 Subject: [PATCH 3/3] Update post review --- RELEASING.md | 61 +++++++--------------------------------------------- 1 file changed, 8 insertions(+), 53 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 28b8daa3f..3694cc3b2 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,38 +1,9 @@ -## Install Github CLI +## Requirements +* [github client](https://github.com/cli/cli#installation) +* [gitchub_changelog_generator](https://github.com/github-changelog-generator) +* [github access token](https://github.com/github-changelog-generator/github-changelog-generator#github-token) -Install to use the command lines below. - -Alternatively can use the github website but ensure you follow the all the --labels --titles etc in the `gh` command lines below. - -https://github.com/cli/cli#installation - -For rpi: - -```bash -sudo apt update -sudo apt install gh -``` - -## Install github_changelog_generator - -If not already installed - -github_changelog_generator requires Ruby to be installed. -Instructions vary based on OS. For rpi: - -```bash -sudo apt-get install rbenv -sudo apt-get install ruby-dev -sudo gem install github_changelog_generator -``` - -## Get a githubtoken - -Or refresh an existing token - -This allows the generator to access github.com - -visit https://github.com/github-changelog-generator/github-changelog-generator#github-token +## Export changelog token ```bash export CHANGELOG_GITHUB_TOKEN=token @@ -40,14 +11,11 @@ export CHANGELOG_GITHUB_TOKEN=token ## Set release information -Replace 0.7.0.dev2 with intended new version number - 0.3.5 should always be the previous release as it's the last pyhs100 release in HISTORY.md which is the changelog prior to github release notes. ```bash -export NEW_RELEASE=0.7.0.dev2 +export NEW_RELEASE=x.x.x.devx export PREVIOUS_RELEASE=0.3.5 - ``` ## Create a branch for the release @@ -69,11 +37,6 @@ poetry version $NEW_RELEASE ```bash poetry install --all-extras --sync -``` - -If you want to update all dependencies to latest: - -```bash poetry update ``` @@ -84,9 +47,7 @@ pre-commit run --all-files pytest kasa ``` -## Create release summary - -Skip this step for dev releases +## Create release summary (skip for dev releases) Write a short and understandable summary for the release. Can include images. @@ -139,13 +100,7 @@ Warning: PR 908 merge commit was not found in the release branch or tagged git h ```bash export RELEASE_NOTES=$(grep -Poz '(?<=\# Changelog\n\n)(.|\n)+?(?=\#\#)' CHANGELOG.md | tr '\0' '\n' ) -echo "$RELEASE_NOTES" -``` - -Check the release notes output and if it doesn't look right or the command doesn't work just copy paste from CHANGELOG.md for the latest release: - -```bash -export RELEASE_NOTES="paste release notes from CHANGELOG.md here" +echo "$RELEASE_NOTES" # Check the output and copy paste if neccessary ``` ## Commit and push the changed files