Skip to content

feat: add release automation command /release with version bump and CHANGELOG update logic #1204

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

Open
ttypic wants to merge 1 commit into
base: main
Choose a base branch
from
+60 −13
Open

feat: add release automation command /release with version bump and CHANGELOG update logic #1204

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
53 changes: 53 additions & 0 deletions .claude/commands/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
description: "Create a release branch, bump version, and update CHANGELOG. Usage: /release patch|minor|major"
allowed-tools: Bash, Read, Edit, Write
---

Read the current version from `gradle.properties` (the `VERSION_NAME` property).

The bump type is: $ARGUMENTS

Compute the new version by incrementing the appropriate component of the current version:
- `patch` — increment the third number, keep major and minor (e.g. 1.7.0 → 1.7.1)
- `minor` — increment the second number, reset patch to 0 (e.g. 1.7.0 → 1.8.0)
- `major` — increment the first number, reset minor and patch to 0 (e.g. 1.7.0 → 2.0.0)

Then perform these steps in order:

1. Run `git checkout -b release/NEW_VERSION`
2. Replace `OLD_VERSION` with `NEW_VERSION` in all of the following files:
Copy link
Collaborator

@sacOO7 sacOO7 Mar 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe apply regex here to change all versions in all files excluding CHANGELOG.md.
So, we don't need to manually specify each file.

Copy link
Contributor Author

@ttypic ttypic Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I afraid if we ask him to use regexp we can accidentally bump libraries that we shouldn't simply because they have the same version as ably-java. I want to be extremely caution here

Copy link
Collaborator

@sacOO7 sacOO7 Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add some exceptions, then regex should work fine wdyt

- `gradle.properties` — the `VERSION_NAME` property
- `README.md` — 3 places: Maven `<version>`, Gradle `implementation '…'`, and LiveObjects `runtimeOnly("…")`
- `CONTRIBUTING.md` — the `implementation files('libs/ably-android-OLD_VERSION.aar')` line
- `lib/src/test/java/io/ably/lib/test/realtime/RealtimeHttpHeaderTest.java` — the hardcoded `"ably-java/OLD_VERSION"` string in the agent header assertion
Commit all five files together with message: `chore: bump version to NEW_VERSION`
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The step lists 4 files to update (gradle.properties, README.md, CONTRIBUTING.md, RealtimeHttpHeaderTest.java) but then says "Commit all five files together". Please reconcile the count (either list the missing file or change to four).

Suggested change
Commit all five files together with message: `chore: bump version to NEW_VERSION`
Commit all four files together with message: `chore: bump version to NEW_VERSION`

Copilot uses AI. Check for mistakes.
3. Fetch merged PRs since the last release tag using:
```
gh pr list --state merged --base main --json number,title,mergedAt --limit 200
```
Then get the date of the last release tag with:
```
git log vOLD_VERSION --format="%aI" -1
```
Filter the PRs to only those merged after that tag date. Format each as:
```
- Short, one sentence summary from PR title and description [#NUMBER](https://github.com/ably/ably-java/pull/NUMBER)
```
Comment on lines +24 to +35
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Step 3 says to write a summary from the PR title and description, but the suggested gh pr list command only fetches number,title,mergedAt so the description/body isn't available. Either include body in the JSON fields (and/or switch to gh pr view per PR) or update the instruction to use only the title.

Copilot uses AI. Check for mistakes.
If the tag doesn't exist or there are no merged PRs, use a single `-` placeholder bullet instead.
Comment on lines +28 to +36
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instructions mention handling the case where tag vOLD_VERSION doesn't exist, but step 3 unconditionally runs git log vOLD_VERSION ..., which will error in that scenario. Add an explicit check/fallback (e.g., detect missing tag and skip date filtering / use the latest tag) so the command remains usable.

Suggested change
Then get the date of the last release tag with:
```
git log vOLD_VERSION --format="%aI" -1
```
Filter the PRs to only those merged after that tag date. Format each as:
```
- Short, one sentence summary from PR title and description [#NUMBER](https://github.com/ably/ably-java/pull/NUMBER)
```
If the tag doesn't exist or there are no merged PRs, use a single `-` placeholder bullet instead.
Then get the date of the last release tag, only if the tag exists:
```bash
if git rev-parse -q --verify "vOLD_VERSION^{tag}" >/dev/null; then
git log vOLD_VERSION --format="%aI" -1
else
# Tag doesn't exist; skip date filtering and consider all fetched PRs as candidates.
echo ""
fi

If a tag date is available, filter the PRs to only those merged after that tag date. If no tag date is available (because the tag doesn't exist), either:

  • treat all fetched PRs as candidates, or
  • if there are no relevant PRs to include, fall back to the placeholder below.
    Format each included PR as:
- Short, one sentence summary from PR title and description [#NUMBER](https://github.com/ably/ably-java/pull/NUMBER)

If, after applying this logic, there are no PRs to list, use a single - placeholder bullet instead.

Copilot uses AI. Check for mistakes.

4. In `CHANGELOG.md`, insert the following block immediately after the `# Change Log` heading (and its trailing blank line), before the first existing `## [` version entry:

```
## [NEW_VERSION](https://github.com/ably/ably-java/tree/vNEW_VERSION)

[Full Changelog](https://github.com/ably/ably-java/compare/vOLD_VERSION...vNEW_VERSION)

### What's Changed

BULLETS_FROM_STEP_3

```

5. Commit `CHANGELOG.md` with message: `docs: update CHANGELOG for NEW_VERSION release`

After completing all steps, show the user a summary of what was done. If PRs were found, list them. If the placeholder `-` was used instead, remind them to fill in the `### What's Changed` bullet points in `CHANGELOG.md` before merging.
Copy link
Collaborator

@sacOO7 sacOO7 Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add one more step, to validate changes made in accordance with original requirement and fix them if anything missing found

20 changes: 7 additions & 13 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,19 +244,13 @@ implementation files('libs/ably-android-1.7.0.aar')

This library uses [semantic versioning](http://semver.org/). For each release, the following needs to be done:

1. Create a branch for the release, named like `release/1.2.4` (where `1.2.4` is what you're releasing, being the new version)
2. Replace all references of the current version number with the new version number (check the [README.md](./README.md) and [gradle.properties](./gradle.properties)) and commit the changes
3. Run [`github_changelog_generator`](https://github.com/github-changelog-generator/github-changelog-generator) to automate the update of the [CHANGELOG](./CHANGELOG.md). This may require some manual intervention, both in terms of how the command is run and how the change log file is modified. Your mileage may vary:
- The command you will need to run will look something like this: `github_changelog_generator -u ably -p ably-java --since-tag v1.2.3 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`. Generate token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token).
- Using the command above, `--output delta.md` writes changes made after `--since-tag` to a new file.
- The contents of that new file (`delta.md`) then need to be manually inserted at the top of the `CHANGELOG.md`, changing the "Unreleased" heading and linking with the current version numbers.
- Also ensure that the "Full Changelog" link points to the new version tag instead of the `HEAD`.
4. Commit [CHANGELOG](./CHANGELOG.md)
5. Make a PR against `main`
6. Once the PR is approved, merge it into `main`
7. Create the release and the release tag on Github including populating the release notes
8. Use the [GitHub action](https://github.com/ably/ably-java/actions/workflows/release.yaml) to publish the release. Run the workflow on the latest release tag.
9. Create the entry on the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/))
1. Run `/release patch|minor|major` in Claude Code — this creates the release branch, bumps the version in all required files, and populates the [CHANGELOG](./CHANGELOG.md) with merged PRs since the last tag automatically
Copy link
Collaborator

@sacOO7 sacOO7 Mar 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't recommend having claude dependent release process, since it frequently goes down and can delay the release. Maybe you should create a separate section

### Release using LLM

Add relevant steps there. maybe, sometime in near future, if claude gets replaced by other LLM, the release docs will still be relevant ( both manual and automated )

2. Review the `### What's Changed` entries in [CHANGELOG.md](./CHANGELOG.md) and adjust if needed, then commit any edits
3. Make a PR against `main`
4. Once the PR is approved, merge it into `main`
5. Create the release and the release tag on Github including populating the release notes
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line uses "Github"; repository/docs elsewhere use the correct capitalization "GitHub". Please update for consistency (e.g., "Create the release and the release tag on GitHub …").

Suggested change
5. Create the release and the release tag on Github including populating the release notes
5. Create the release and the release tag on GitHub including populating the release notes

Copilot uses AI. Check for mistakes.
6. Use the [GitHub action](https://github.com/ably/ably-java/actions/workflows/release.yaml) to publish the release. Run the workflow on the latest release tag.
7. Create the entry on the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/))

### Signing

Expand Down
Loading