@@ -25,36 +25,24 @@ Update both files:
2525
2626## Releasing
2727
28- Releases are automated by [ release-please] ( https://github.com/googleapis/release-please ) .
29- You do not run ` make release ` in normal flow — the bot does it for you.
30-
31- ** Normal flow:**
32-
33- 1 . Open a PR with a Conventional Commits title (` feat: ... ` , ` fix: ... ` , ` docs: ... ` ).
34- The PR title lint blocks merge if the prefix is missing.
35- 2 . Merge the PR to main.
36- 3 . ` release-please ` reads commits since the last release tag and, if any
37- ` feat: ` / ` fix: ` are present, opens (or updates) a "Release PR"
38- titled ` chore(main): release X.Y.Z ` with an auto-generated
39- ` CHANGELOG.md ` entry and a new version computed via semver:
40- - ` feat: ` → minor bump
41- - ` fix: ` / ` perf: ` → patch bump
42- - any ` BREAKING CHANGE: ` footer → major bump
43- 4 . Merge the Release PR when you're ready to ship. The bot creates the
44- ` vX.Y.Z ` tag, which triggers ` publish.yml ` → build → PyPI upload.
45-
46- The version itself lives in git tags. ` pyproject.toml ` has no ` version `
47- field — ` setuptools-scm ` derives it from the tag at build time. The
48- ` .release-please-manifest.json ` file tracks the current released
49- version for release-please's own bookkeeping; you don't edit it by hand.
50-
51- ** Manual escape hatch (rare):**
52-
53- If you ever need to release out of band — e.g. a security fix that
54- shouldn't wait for the next Release PR cycle — ` make release ` /
55- ` make release-minor ` / ` make release-major ` still work. They read the
56- latest tag, compute the next version, tag, and push. Use only when the
57- release-please flow can't be used.
58-
59- Don't tag manually outside the Makefile — the targets enforce clean
60- tree + on main + up-to-date.
28+ The version lives in git tags. ` pyproject.toml ` has no ` version ` field —
29+ ` setuptools-scm ` derives it from the latest ` v* ` tag at build time.
30+
31+ After merging a PR with user-visible changes, publish to PyPI from main:
32+
33+ ``` bash
34+ git checkout main && git pull
35+ make release # patch bump (e.g. 0.3.5 → 0.3.6) — bug fixes only
36+ make release-minor # minor bump (e.g. 0.3.5 → 0.4.0) — new features, backwards-compat
37+ make release-major # major bump (e.g. 0.3.5 → 1.0.0) — breaking changes
38+ ```
39+
40+ Each target reads the latest tag, computes the next, tags it, and pushes
41+ the tag. No source file is bumped; no "Release vX.Y.Z" commits land on
42+ main. The ` publish.yml ` workflow runs on tag push and publishes to PyPI
43+ via trusted publisher (setuptools-scm bakes the tag's version into the
44+ built artifacts).
45+
46+ Pick the bump from semver: new public API = minor, only bug fixes =
47+ patch, backwards-incompatible = major. Don't tag manually outside the
48+ Makefile — the targets enforce clean tree + on main + up-to-date.
0 commit comments