From 6f14330e093775460eed7b700ba86bc9894a6f20 Mon Sep 17 00:00:00 2001
From: "Steven B." <51370195+sdb9696@users.noreply.github.com>
Date: Wed, 31 Jul 2024 17:56:06 +0100
Subject: [PATCH] Update RELEASING.md for patch releases (#1076)

---
 RELEASING.md | 187 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 166 insertions(+), 21 deletions(-)

diff --git a/RELEASING.md b/RELEASING.md
index e42e1c87..a330c002 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,3 +1,5 @@
+# Releasing
+
 ## Requirements
 * [github client](https://github.com/cli/cli#installation)
 * [gitchub_changelog_generator](https://github.com/github-changelog-generator)
@@ -18,7 +20,9 @@ export NEW_RELEASE=x.x.x.devx
 export PREVIOUS_RELEASE=0.3.5
 ```
 
-## Create a branch for the release
+## Normal releases from master
+
+### Create a branch for the release
 
 ```bash
 git checkout master
@@ -27,35 +31,35 @@ git rebase upstream/master
 git checkout -b release/$NEW_RELEASE
 ```
 
-## Update the version number
+### Update the version number
 
 ```bash
 poetry version $NEW_RELEASE
 ```
 
-## Update dependencies
+### Update dependencies
 
 ```bash
 poetry install --all-extras --sync
 poetry update
 ```
 
-## Run pre-commit and tests
+### Run pre-commit and tests
 
 ```bash
 pre-commit run --all-files
 pytest kasa
 ```
 
-## Create release summary (skip for dev releases)
+### 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
+#### Create $NEW_RELEASE milestone in github
 
 If not already created
 
-### Create new issue linked to the milestone
+#### Create new issue linked to the milestone
 
 ```bash
 gh issue create --label "release-summary" --milestone $NEW_RELEASE --title "$NEW_RELEASE Release Summary" --body "## Release Summary"
@@ -63,7 +67,7 @@ gh issue create --label "release-summary" --milestone $NEW_RELEASE --title "$NEW
 
 You can exclude the --body option to get an interactive editor or go into the issue on github and edit there.
 
-### Close the issue
+#### Close the issue
 
 Either via github or:
 
@@ -71,11 +75,11 @@ Either via github or:
 gh issue close ISSUE_NUMBER
 ```
 
-## Generate changelog
+### Generate changelog
 
 Configuration settings are in `.github_changelog_generator`
 
-### For pre-release
+#### For pre-release
 
 EXCLUDE_TAGS will exclude all dev tags except for the current release dev tags.
 
@@ -87,7 +91,7 @@ echo "$EXCLUDE_TAGS"
 github_changelog_generator --future-release $NEW_RELEASE --exclude-tags-regex "$EXCLUDE_TAGS"
 ```
 
-### For production
+#### For production
 
 ```bash
 github_changelog_generator --future-release $NEW_RELEASE --exclude-tags-regex 'dev\d$'
@@ -99,28 +103,28 @@ Warning: PR 908 merge commit was not found in the release branch or tagged git h
 ```
 
 
-## Export new release notes to variable
+### 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
+### 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 a PR for the release, merge it, and re-fetch the master
 
-### Create the PR
+#### 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
+#### Merge the PR once the CI passes
 
 Create a squash commit and add the markdown from the PR description to the commit description.
 
@@ -136,7 +140,7 @@ git fetch upstream master
 git rebase upstream/master
 ```
 
-## Create a release tag
+### 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.
 
@@ -145,21 +149,162 @@ git tag --annotate $NEW_RELEASE -m "$RELEASE_NOTES"
 git push upstream $NEW_RELEASE
 ```
 
-## Create release
+### Create release
 
-### Pre-releases
+#### Pre-releases
 
 ```bash
 gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=false --prerelease
 
 ```
 
-### Production release
+#### Production release
 
 ```bash
 gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=true
 ```
 
-## Manually publish the release
+### Manually publish the release
 
 Go to the linked URL, verify the contents, and click "release" button to trigger the release CI.
+
+## Patch releases
+
+This requires git commit signing to be enabled.
+
+https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification
+
+### Create release branch
+
+#### For the first patch release since a new release only
+
+```bash
+export NEW_RELEASE=x.x.x.x
+export CURRENT_RELEASE=x.x.x
+```
+
+```bash
+git fetch upstream $CURRENT_RELEASE
+git checkout patch
+git fetch upstream patch
+git rebase upstream/patch
+git fetch upstream $CURRENT_RELEASE
+git merge $CURRENT_RELEASE --ff-only
+git push upstream patch -u
+git checkout -b release/$NEW_RELEASE
+```
+
+#### For subsequent patch releases
+
+```bash
+export NEW_RELEASE=x.x.x.x
+```
+
+```bash
+git checkout patch
+git fetch upstream patch
+git rebase upstream/patch
+git checkout -b release/$NEW_RELEASE
+```
+### Cherry pick required commits
+
+```bash
+git cherry-pick commitSHA1 -S
+git cherry-pick commitSHA2 -S
+```
+
+### Update the version number
+
+```bash
+poetry version $NEW_RELEASE
+```
+
+### Manually edit the changelog
+
+github_changlog generator_does not work with patch releases so manually add the section for the new release to CHANGELOG.md.
+
+### 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" -S
+git push upstream release/$NEW_RELEASE -u
+```
+
+### Create a PR for the release, merge it, and re-fetch patch
+
+#### Create the PR
+```
+gh pr create --title "$NEW_RELEASE" --body "$RELEASE_NOTES" --label release-prep --base patch
+```
+
+#### Merge the PR once the CI passes
+
+Create a **merge** commit and add the markdown from the PR description to the commit description.
+
+```bash
+gh pr merge --merge --body "$RELEASE_NOTES"
+```
+
+### Rebase local patch
+
+```bash
+git checkout patch
+git fetch upstream patch
+git rebase upstream/patch
+```
+
+### Create a release tag
+
+```bash
+git tag -s --annotate $NEW_RELEASE -m "$RELEASE_NOTES"
+git push upstream $NEW_RELEASE
+```
+
+### Create release
+
+```bash
+gh release create "$NEW_RELEASE" --verify-tag --notes-from-tag --title "$NEW_RELEASE" --draft --latest=true
+```
+Then go into github, review and release
+
+### Merge patch back to master
+
+```bash
+git checkout master
+git fetch upstream master
+git rebase upstream/master
+git checkout -b janitor/merge_patch
+git fetch upstream patch
+git merge upstream/patch --no-commit
+git diff --name-only --diff-filter=U | xargs git checkout upstream/master
+git diff --staged
+# The only diff should be the version in pyproject.toml and CHANGELOG.md
+# unless a change made on patch that was not part of a cherry-pick commit
+# If there are any other unexpected diffs `git checkout upstream/master [thefilename]`
+git commit -m "Merge patch into local master" -S
+git push upstream janitor/merge_patch -u
+gh pr create --title "Merge patch into master" --body '' --label release-prep --base master
+```
+
+#### Temporarily allow merge commits to master
+
+1. Open [repository settings](https://github.com/python-kasa/python-kasa/settings)
+2. From the left select `Rules` > `Rulesets`
+3. Open `master` ruleset, under `Bypass list` select `+ Add bypass`
+4. Check `Repository admin` > `Add selected`, select `Save changes`
+
+#### Merge commit the PR
+```bash
+gh pr merge --merge --body ""
+```
+#### Revert allow merge commits
+
+1. Under `Bypass list` select `...` next to `Repository admins`
+2. `Delete bypass`, select `Save changes`