Update release playbook (#932)

Updates the RELEASING.md runbook with more steps and scripts.
Excludes dev release tags for prior releases.
Updates github_changelog_generator config to exclude pull requests
with the release-prep label from the changelog.

Co-authored-by: sdb9696

.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

RELEASING.md

@@ -1,57 +1,162 @@
-1. Set release information
+## 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)
+
+## Export changelog token
 
 ```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
+export CHANGELOG_GITHUB_TOKEN=token
 ```
 
-2. Update the version number
+## Set release information
+
+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=x.x.x.devx
+export PREVIOUS_RELEASE=0.3.5
+```
+
+## Create a branch for the release
+
+```bash
+git checkout master
+git fetch upstream master
+git rebase upstream/master
+git checkout -b release/$NEW_RELEASE
+```
+
+## Update the version number
 
 ```bash
 poetry version $NEW_RELEASE
 ```
 
-3. Write a short and understandable summary for the release.
-
-* 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
-
-3. Generate changelog
+## Update dependencies
+
+```bash
+poetry install --all-extras --sync
+poetry update
+```
+
+## Run pre-commit and tests
+
+```bash
+pre-commit run --all-files
+pytest kasa
+```
+
+## Create release summary (skip for dev releases)
+
+Write a short and understandable summary for the release.  Can include images.
+
+### Create $NEW_RELEASE milestone in github
+
+If not already created
+
+### Create new issue linked to the milestone
+
+```bash
+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.
+
+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
-# 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$'
 ```
 
-Remove '--exclude-tags-regex' for dev releases.
-
-4. Commit the changed files
-
-```bash
-git commit -av
+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
 ```
 
-5. Create a PR for the release.
 
-6. Get it merged, fetch the upstream master
+## Export new release notes to variable
+
+```bash
+export RELEASE_NOTES=$(grep -Poz '(?<=\# Changelog\n\n)(.|\n)+?(?=\#\#)' CHANGELOG.md | tr '\0' '\n' )
+echo "$RELEASE_NOTES"  # Check the output and copy paste if neccessary
+```
+
+## 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
 ```
 
-7. Tag the release (add short changelog as a tag commit message), push the tag to git
+## Create a release tag
+
+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 -a $NEW_RELEASE
+git tag --annotate $NEW_RELEASE -m "$RELEASE_NOTES"
 git push upstream $NEW_RELEASE
 ```
 
-All tags on master branch will trigger a new release on pypi.
+## Create release
 
-8. Click the "Draft a new release" button on github, select the new tag and copy & paste the changelog into the description.
+### Pre-releases
+
+```bash
+gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=false --prerelease
+
+```
+
+### Production release
+
+```bash
+gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=true
+```
+
+## Manually publish the release
+
+Go to the linked URL, verify the contents, and click "release" button to trigger the release CI.