From 82238f3f85446fdd786f6d18ab37966931153fa2 Mon Sep 17 00:00:00 2001 From: evgeny Date: Wed, 8 Apr 2026 19:18:14 +0100 Subject: [PATCH] docs: add automated release steps to contributing guide and document Claude Code process - Expanded release instructions in `CONTRIBUTING.md` to include automated release steps using Claude Code. - Clarified the manual release process as a fallback. - Added `.claude/skills/release/SKILL.md` to define the automated process and usage details. --- .claude/skills/release/SKILL.md | 69 +++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 13 ++++++- 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/release/SKILL.md diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md new file mode 100644 index 000000000..f4a94c458 --- /dev/null +++ b/.claude/skills/release/SKILL.md @@ -0,0 +1,69 @@ +--- +description: "Create a release branch, bump version, update CHANGELOG, and regenerate lock files. Usage: /release patch|minor|major" +allowed-tools: Bash, Read, Edit, Write, Glob, Grep +--- + +Read the current version from `pubspec.yaml` (the `version` 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.2.43 → 1.2.44) +- `minor` — increment the second number, reset patch to 0 (e.g. 1.2.43 → 1.3.0) +- `major` — increment the first number, reset minor and patch to 0 (e.g. 1.2.43 → 2.0.0) + +Then perform these steps in order: + +1. Run `git checkout -b release/NEW_VERSION` + +2. Update the version in these files: + - `pubspec.yaml` — the `version` property + - `README.md` — the `ably_flutter: ^OLD_VERSION` line in the Installation section (update to `^NEW_VERSION`) + +3. Regenerate lock files: + + a. Run `flutter pub get` in `example/` and `test_integration/` to update their `pubspec.lock` files: + ``` + cd example && flutter pub get && cd .. + cd test_integration && flutter pub get && cd .. + ``` + If either directory doesn't exist, skip it and note it in the summary. + + b. Regenerate iOS Podfile.lock files by running: + ``` + pod install --project-directory=example/ios + pod install --project-directory=test_integration/ios + ``` + If CocoaPods is not installed or either directory doesn't exist, skip that directory and note it in the summary. + +4. Commit all changed files together with message: `chore: bump version to NEW_VERSION` + Stage: `pubspec.yaml`, `README.md`, `example/pubspec.lock`, `example/ios/Podfile.lock`, `test_integration/pubspec.lock`, `test_integration/ios/Podfile.lock` (only include files that actually changed). + +5. Fetch merged PRs since the last release tag: + ``` + 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 [#NUMBER](https://github.com/ably/ably-flutter/pull/NUMBER) + ``` + If the tag doesn't exist or there are no merged PRs, use a single `-` placeholder bullet instead. + +6. In `CHANGELOG.md`, insert the following block immediately after the `# Changelog` heading (and its trailing blank line), before the first existing `## [` version entry: + +``` +## [NEW_VERSION](https://github.com/ably/ably-flutter/tree/vNEW_VERSION) + +[Full Changelog](https://github.com/ably/ably-flutter/compare/vOLD_VERSION...vNEW_VERSION) + +BULLETS_FROM_STEP_5 + +``` + +7. Commit `CHANGELOG.md` with message: `docs: update CHANGELOG for NEW_VERSION` + +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 the user to fill in the bullet points in `CHANGELOG.md` before merging. Also remind them of the remaining manual steps: push the branch, open a PR, get approval, merge, tag `vNEW_VERSION`, and publish via the GitHub Release Workflow. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 202d8e064..d725c0615 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,18 @@ Documentation stored in repository should follow the schema defined in [Ably Tem When referencing images in markdown files, using a local path such as `images/android.png`, for example `![An android device running on API level 30](images/android.png)` will result in the image missing on pub.dev README preview. Therefore, we currently reference images through the github.com URL path (`https://github.com/ably/ably-flutter/raw/`), for example to reference `images/android.png`, we would use `![An android device running on API level 30](https://github.com/ably/ably-flutter/raw/main/images/android.png)`. [A suggestion](https://github.com/dart-lang/pub-dev/issues/5068) has been made to automatically replace this relative image path to the github URL path. -## Release Process +## Release Process (Claude Code) + +1. Ensure that all work intended for this release has landed to `main` +2. 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 +3. Review the `### What's Changed` entries in [CHANGELOG.md](./CHANGELOG.md) and adjust if needed, then commit any edits +4. Create a release PR (ensure you include an SDK Team Engineering Lead and the SDK Team Product Manager as reviewers) and gain approvals for it, then merge that to `main` +5. Create a tag named like `v2.0.1` and push it to GitHub - e.g. `git tag v2.0.1 && git push origin v2.0.1` +6. Create the release on GitHub including populating the release notes +7. Go to the [Release Workflow](https://github.com/ably/ably-flutter/actions/workflows/release.yaml) and ask [ably/team-sdk](https://github.com/orgs/ably/teams/team-sdk) member to approve publishing to the pub.dev registry +8. Update the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)) with these changes + +## Release Process (Manual) Releases should always be made through a release pull request (PR), which needs to bump the version number and add to the [change log](CHANGELOG.md). For an example of a previous release PR, see [#89](https://github.com/ably/ably-flutter/pull/89).