Debian Codegraph @

.claude/commands/release.md

raw
1 ---
2 description: Propose and create the next release tag (final or release candidate)
3 ---
4
5 # Release Command
6
7 Create the next versioned git tag. The GitHub Actions release workflow fires automatically on any `v*` tag push, handling GitHub Release creation and PyPI publishing — including pre-releases, which are published to the real PyPI (not Test PyPI) with pre-release status.
8
9 ## Input
10
11 The user may optionally pass `rc` to create a release candidate instead of a final release.
12
13 ## Steps to Execute
14
15 ### 1. Validate Branch and Sync Tags
16
17 Run the following commands:
18
19 ```bash
20 git rev-parse --abbrev-ref HEAD
21 git fetch --tags
22 ```
23
24 - If HEAD is detached or the branch is not `master`, **stop and tell the user**. Tagging from a non-master branch is almost certainly a mistake. Do not proceed unless the user explicitly confirms they know what they're doing and want to tag this commit anyway.
25 - The `git fetch --tags` ensures the local tag list matches the remote before any version analysis — a developer may have pushed a tag that isn't local yet.
26
27 ### 2. Determine the Latest Tag
28
29 Run:
30 ```bash
31 git tag --sort=-version:refname | head -20
32 ```
33
34 Identify:
35 - **Latest final release tag** — highest `vX.Y.Z` tag without a pre-release suffix (e.g. `v0.6.0`)
36 - **Latest RC tag for the next version** — if any `vX.Y.Z-rc.N` tag exists beyond the latest final release, note the highest N
37
38 ### 3. Analyze Commits Since Last Final Release
39
40 Run:
41 ```bash
42 git log <latest-final-tag>..HEAD --format="%s%n%b%n---"
43 ```
44
45 This captures both the subject line and the full message body, which is necessary because `BREAKING CHANGE:` may appear in the commit footer rather than the subject (per the Conventional Commits spec).
46
47 Classify across the full output of each commit using these rules:
48
49 | Indicator | Bump |
50 |-----------|------|
51 | Subject contains `!` after the type (e.g. `feat!:`, `fix!:`), **or** any line in the body/footer contains `BREAKING CHANGE:` | **major** |
52 | Subject starts with `feat` (and no breaking change detected) | **minor** |
53 | Only `fix`, `build`, `chore`, `ci`, `docs`, `refactor`, `test`, `perf`, `style` | **patch** |
54
55 Apply the highest-priority bump found.
56
57 If there are **no commits** since the last final release, stop and tell the user there is nothing to release.
58
59 ### 4. Propose the Next Version
60
61 Compute the proposed tag from the latest final release:
62
63 - **major bump**: increment major, reset minor and patch to 0 → `vX+1.0.0`
64 - **minor bump**: increment minor, reset patch to 0 → `vX.Y+1.0`
65 - **patch bump**: increment patch → `vX.Y.Z+1`
66
67 **If creating a release candidate (`rc` argument passed):**
68
69 Check whether an RC tag for this proposed version already exists (e.g. `vX.Y.Z-rc.1`). If yes, increment N. Otherwise start at `-rc.1`.
70
71 Final proposed tag examples:
72 - Final release: `v0.7.0`
73 - First RC: `v0.7.0-rc.1`
74 - Subsequent RC: `v0.7.0-rc.2`
75
76 ### 5. Present a Summary and Ask for Confirmation
77
78 Display a clear summary to the user:
79
80 ```
81 Latest final release : v0.6.0
82 Commits since release: 51
83 Bump type : minor (new features detected)
84 Proposed tag : v0.7.0 [or v0.7.0-rc.1 for RC]
85
86 Notable commits:
87 feat(exo): add ExoFilterPump controllable switch
88 feat(exo): add ExoErrorSensor for diagnostic error fields
89 feat: add token refresh with fallback to full re-login on 401
90 fix: cleanup retry logic for 401/429
91 fix: update iAqua session URL to v2 r-api endpoint
92 ... (only feat/fix/breaking — skip build/chore/ci/docs bumps)
93
94 Note: RC tags are published to the real PyPI (pre-release status).
95 pip install iaqualink won't pick them up; pip install --pre will.
96
97 Shall I create and push tag <proposed-tag>? (yes/no)
98 ```
99
100 Wait for explicit confirmation before proceeding. If the user suggests a different version, use that instead.
101
102 ### 6. Create and Push the Tag
103
104 Once confirmed, create an **annotated** tag (stores tagger identity, timestamp, and message — preferred for release tags and required for `git describe` to work correctly):
105
106 ```bash
107 git tag -a <proposed-tag> -m "Release <proposed-tag>"
108 git push origin <proposed-tag>
109 ```
110
111 ### 7. Report Outcome
112
113 Tell the user:
114 - The tag that was created and pushed
115 - That the GitHub Actions release workflow has been triggered
116 - The GitHub Actions URL to monitor progress: `https://github.com/flz/iaqualink-py/actions`
117 - For RCs: this publishes to the real PyPI as a pre-release (`pip install --pre iaqualink` to install)
118 - For final releases: this publishes to PyPI as a stable release
119
120 ## Error Handling
121
122 - If `git push` fails (e.g. tag already exists remotely), report the error clearly and do not retry automatically.
123 - If the working tree has uncommitted changes, warn the user but do not block — a tag points to a commit, not the working tree.
124 - If no conventional commit prefixes are found, default to a **patch** bump and note the assumption.