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