Skip to content

Update RELEASING.md for patch releases #1076

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sdb9696 merged 3 commits into from
Jul 31, 2024
Merged

Update RELEASING.md for patch releases #1076

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c0d7397
Update RELEASING.md for patch releases
sdb9696 Jul 18, 2024
7d98d27
Add step for merging back to master
sdb9696 Jul 29, 2024
5b5f71f
Merge branch 'master' into janitor/update_releasing
sdb9696 Jul 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 166 additions & 21 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Releasing

## Requirements
* [github client](https://github.com/cli/cli#installation)
* [gitchub_changelog_generator](https://github.com/github-changelog-generator)
Expand All @@ -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
Expand All @@ -27,55 +31,55 @@ 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"
```

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:

```bash
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.

Expand All @@ -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$'
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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`