|
| 1 | +# Release guide |
| 2 | + |
| 3 | +This project uses [release-please](https://github.com/googleapis/release-please) via a |
| 4 | +`workflow_dispatch`-triggered GitHub Actions workflow. This document explains how to cut |
| 5 | +a release and what to watch out for. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## Versioning rules for this project |
| 10 | + |
| 11 | +We are pre-1.0.0. Semver conventions are relaxed: |
| 12 | + |
| 13 | +| Change type | Bump | Example | |
| 14 | +|--- |--- |--- | |
| 15 | +| Breaking change | **Minor** (`0.x.0`) | `0.9.0` → `0.10.0` | |
| 16 | +| Everything else | **Patch** (`0.0.x`) | `0.9.7` → `0.9.8` | |
| 17 | + |
| 18 | +Major bumps (`1.0.0`) are reserved for a deliberate stable-API graduation decision — not for |
| 19 | +routine breaking changes. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Cutting a release |
| 24 | + |
| 25 | +1. Go to **Actions → release-please** and click **Run workflow**. |
| 26 | +2. Choose a bump type: |
| 27 | + - `patch` — bugfixes, docs, small changes |
| 28 | + - `minor` — breaking changes (see above) |
| 29 | + - `explicit` — you specify the exact version string (e.g. `0.10.0` or `0.10.0-beta.1`) |
| 30 | +3. The workflow creates a release PR. Review it, then merge. |
| 31 | +4. The GitHub Release and tag are created automatically on merge. |
| 32 | + |
| 33 | +> **Note — release-please only understands `auto` or an explicit version string.** |
| 34 | +> The `patch`, `minor`, and `major` options in the workflow dropdown are conveniences |
| 35 | +> implemented in the workflow. The workflow reads the current manifest version, computes |
| 36 | +> the next version (e.g. `0.9.7` + patch = `0.9.8`), and passes that computed string |
| 37 | +> to release-please as an explicit `Release-As:` commit — exactly the same as choosing |
| 38 | +> `explicit` and typing it yourself. There is no native patch/minor/major mode in |
| 39 | +> release-please. This is why `explicit` is always the safest option when in doubt — |
| 40 | +> you are just skipping the arithmetic step. |
| 41 | +
|
| 42 | +--- |
| 43 | + |
| 44 | +## When to use `explicit` |
| 45 | + |
| 46 | +Use `explicit` and type the version yourself in any of these situations: |
| 47 | + |
| 48 | +**After a beta or non-conventional tag.** |
| 49 | +If the previous release was something like `0.9.7-beta.1`, release-please tracks the |
| 50 | +base semver (`0.9.7`) but cannot reliably decide whether the next release should be |
| 51 | +`0.9.7`, `0.9.8`, or `0.10.0`. It will often guess wrong. |
| 52 | + |
| 53 | +The rule of thumb: **if the last tag had a pre-release suffix, always use `explicit` for |
| 54 | +the next release.** |
| 55 | + |
| 56 | +**After a manually created tag.** |
| 57 | +Any tag created outside of the release-please workflow (e.g. hotfixes, manual git tags) |
| 58 | +is invisible to release-please's version logic. Use `explicit` to anchor the next version |
| 59 | +correctly. |
| 60 | + |
| 61 | +**When you want a beta.** |
| 62 | +Release-please does not increment pre-release suffixes automatically. Use `explicit` for |
| 63 | +every beta, incrementing the suffix manually: |
| 64 | +``` |
| 65 | +0.10.0-beta.1 → explicit: 0.10.0-beta.2 → explicit: 0.10.0 |
| 66 | +``` |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## What goes in the changelog |
| 71 | + |
| 72 | +Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) |
| 73 | +for release-please to group them correctly: |
| 74 | + |
| 75 | +``` |
| 76 | +feat: add support for batch check → Added |
| 77 | +fix: correct retry logic for transient errors → Fixed |
| 78 | +docs: update API reference → Documentation |
| 79 | +perf: cache DNS lookups → Changed |
| 80 | +refactor: extract auth helper → (hidden) |
| 81 | +chore: bump dependencies → (hidden) |
| 82 | +``` |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +## Troubleshooting |
| 87 | + |
| 88 | +**"Invalid previous_tag parameter" error.** |
| 89 | +The manifest version does not have a corresponding GitHub Release object. Reset the |
| 90 | +manifest to the last valid tag: |
| 91 | +```bash |
| 92 | +echo '{ ".": "0.x.y" }' > .release-please-manifest.json |
| 93 | +git commit -am "chore: reset manifest to v0.x.y" |
| 94 | +git push origin main |
| 95 | +``` |
| 96 | + |
| 97 | +**Duplicate release PRs.** |
| 98 | +Close all stale ones. The workflow auto-closes stale open PRs on each dispatch, but |
| 99 | +merged duplicates need manual labelling with `autorelease: tagged`. |
| 100 | + |
| 101 | +**Changelog shows everything ungrouped.** |
| 102 | +Make sure `changelog-type` in `release-please-config.json` is set to `"default"`, not |
| 103 | +`"github"`. |
0 commit comments