Skip to content

Commit e566300

Browse files
authored
docs(releasekit): adopt release-please model (#4575)
### Roadmap Update: Release-Please Model & Independent Versioning This PR refactors the `releasekit` roadmap to adopt a **Release-Please** style workflow and introduces a robust **Independent Versioning** strategy for the monorepo. #### Key Changes 1. **New Lifecycle Commands** (replaces monolithic pipeline) - `prepare`: Scans commits, computes bumps (with transitive propagation), updates `pyproject.toml`/lockfiles, generates changelogs, and creates/updates a **Release PR** with an embedded manifest. - `tag`: Triggered on Release PR merge. Parses the manifest, tags the merge commit, and creates a GitHub Release. - `publish`: Triggered on Release creation. Builds with ephemeral pinning, uploads to PyPI, and dispatches to downstream repos. 2. **Versioning Strategy** - **Independent (Default)**: Packages bump based on their own commits. - **Transitive Propagation**: ANY bump in a dependency triggers a **PATCH** bump in all dependents. This ensures lockfiles are updated and fresh pins are used. Releases ripple through the dependency tree. - **Synchronized (Lockstep)**: Optional mode (`synchronize = true`) where all packages share the same version. - **D-11 Updated**: Transitive propagation is now supported as PATCH bumps only (not matching the original bump type), avoiding the [changesets #1011](changesets/changesets#1011) problem. 3. **Cross-Repository Support** - Main repo fires `repository_dispatch` after publish. - Downstream repos run `releasekit prepare`, which detects external updates via `uv lock --upgrade-package`. 4. **Contradictions Resolved** - Removed all `commitback.py` references (replaced with `prepare.py` + `release.py`). - Pipeline rewritten from monolithic 9-step to 3-command split. - Phase 5 renamed from "Post-Pipeline" to "Release-Please". - Mermaid diagram updated with `preparemod` + `releasemod` nodes. - `versioning.py` description updated to reflect transitive propagation + `synchronize` mode. - File tree updated with new modules and test files. #### Architecture **Dependency Tree Propagation** ```text [genkit] v0.5.0 → v0.6.0 (Minor Bump: "feat: core update") │ ▼ [genkit-plugin-vertex-ai] Depends on: genkit Action: v0.5.0 → v0.5.1 (Patch Bump) Reason: "dependency genkit bumped" │ ▼ [sample-app] Depends on: genkit-plugin-vertex-ai Action: v0.1.0 → v0.1.1 (Patch Bump) Reason: "dependency genkit-plugin-vertex-ai bumped" ``` **Release Lifecycle** ```text Developer │ │ pushes to main ▼ ┌───────────────────────────────────────────────────────────────┐ │ STEP 1: PREPARE (releasekit prepare) │ │ │ │ 1. Scan commits per package │ │ 2. Compute bumps + Propagate to dependents (PATCH) │ │ 3. Update pyproject.toml & uv.lock │ │ 4. Generate Changelogs │ │ 5. Create/Update "Release PR" (autorelease: pending) │ └───────────────────────────────────────────────────────────────┘ │ │ merges Release PR ▼ ┌───────────────────────────────────────────────────────────────┐ │ STEP 2: TAG (releasekit tag) │ │ │ │ 1. Find merged PR with "autorelease: pending" │ │ 2. Parse Manifest from PR Body │ │ 3. Tag Merge Commit (per-pkg + umbrella tags) │ │ 4. Create GitHub Release │ │ 5. Label PR "autorelease: tagged" │ └───────────────────────────────────────────────────────────────┘ │ │ triggered by Release creation ▼ ┌───────────────────────────────────────────────────────────────┐ │ STEP 3: PUBLISH (releasekit publish) │ │ │ │ 1. Checkout Tag │ │ 2. Rewrite deps in pyproject.toml (Ephemeral Pinning) │ │ 3. Build Wheels/Sdists │ │ 4. Upload to PyPI │ │ 5. Label PR "autorelease: published" │ │ 6. Dispatch "repository_dispatch" to downstream repos │ └───────────────────────────────────────────────────────────────┘ ```
1 parent 7ed3c77 commit e566300

1 file changed

Lines changed: 168 additions & 34 deletions

File tree

‎tools/releasekit/roadmap.md‎

Lines changed: 168 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,43 @@ pinning, retry with jitter, and crash-safe file restoration.
1010

1111
---
1212

13+
## Versioning Strategy
14+
15+
`releasekit` supports two versioning models for monorepos, configurable via `[tool.releasekit.synchronize]`.
16+
17+
### 1. Independent Versioning (Default)
18+
`synchronize = false` (default)
19+
20+
Packages are versioned independently based on their own changes, but **propagated transitively**:
21+
1. **Direct Bumps**: Commits to a package directory trigger semantic version bumps (Major/Minor/Patch).
22+
2. **Transitive Propagation**: If a package depends on another package that was bumped, it receives a **PATCH bump**.
23+
- **Rule**: ANY bump in a dependency (Major, Minor, or Patch) triggers a Patch bump in all dependents.
24+
- **Why**: Ensures lockfiles and pins are updated to point to the new dependency version.
25+
- **Mental Model**: Releases ripple through the dependency tree. A change in a leaf node (e.g. `genkit`) forces a republication of all consuming nodes.
26+
27+
### 2. Synchronized Versioning (Lockstep)
28+
`synchronize = true`
29+
30+
All packages in the workspace share the same version number.
31+
1. **Compute Max Bump**: Calculate the highest semantic bump across *all* packages based on commits.
32+
2. **Apply globally**: Bump *every* package to that new version.
33+
- Example: `genkit` has a breaking change (Major), so `plugin-vertex-ai` also gets a Major bump, even if unchanged.
34+
- **Use Case**: Frameworks where components must be installed with matching versions (e.g. `genkit==0.6.0` needs `genkit-plugin-x==0.6.0`).
35+
36+
### 3. Cross-Repository Workflow (Plugins)
37+
38+
To support dependent packages in external repositories (e.g. `genkit-community-plugins`):
39+
40+
1. **Trigger**: The main repo (`firebase/genkit`) fires a `repository_dispatch` event upon successful publish.
41+
2. **Action**: The dependent repo runs `releasekit prepare`.
42+
3. **Update**: `prepare` runs `uv lock --upgrade-package genkit` (checking PyPI).
43+
4. **Result**: If `uv.lock` changes:
44+
- Creates a `chore(deps): update genkit` bump.
45+
- Bumps the plugin version (Patch).
46+
- Opens/Updates a Release PR with the dependency update included.
47+
48+
---
49+
1350
## Progress
1451

1552
| Phase | Status | Notes |
@@ -80,32 +117,48 @@ changesets, and lerna issue trackers.
80117
| D-8 | Med | **Attestation support.** `uv publish` auto-discovers `.publish.attestation` files. | Document support. Don't interfere with attestation files. Passthrough `--no-attestations`. | 4 |
81118
| D-9 | Med | **`resolve_check` uses wrong tool.** Plan said `pip install --dry-run`. | Use `uv pip install --dry-run` for consistency. | 3 |
82119
| D-10 | Med | **`gh` CLI not installed.** | Graceful degradation: skip GitHub Releases with warning. Core publish works without `gh`. | 3, 5 |
83-
| D-11 | Med | **Transitive major bump propagation.** [changesets #1011](https://github.com/changesets/changesets/issues/1011) (62 upvotes). | Per-package bump from own commits only. No transitive propagation. | 2 |
120+
| D-11 | Med | **Transitive major bump propagation.** [changesets #1011](https://github.com/changesets/changesets/issues/1011) (62 upvotes). | Transitive propagation as **PATCH bumps only** (not matching the original bump type). Avoids the changesets problem where a transitive dep causes an unexpected Major bump. Configurable via `synchronize` (lockstep) vs independent (default). | 2 |
84121
| D-12 | Med | **`uv version` command overlap.** `uv version --bump` already handles PEP 440. | Evaluate delegating version writing to `uv version --frozen` during Phase 2. | 2 |
85122

86-
### Corrected Pipeline (incorporating D-1 through D-12)
123+
### Corrected Pipeline (Release-Please Model)
124+
125+
The pipeline is split into 3 independent commands, each triggered by a
126+
different CI event. All external tool calls go through the backend shim
127+
layer (see Phase 0).
87128

88-
All external tool calls go through the backend shim layer (see Phase 0).
89129
`vcs.*` = VCS/GitBackend, `pm.*` = PackageManager/UvBackend,
90130
`forge.*` = Forge/GitHubBackend, `registry.*` = Registry/PyPIBackend.
91131

92132
```
93-
0. preflight vcs.is_clean(), pm.lock() --check, forge.is_available() (D-10),
94-
forge.list_releases() concurrent detection (D-6),
95-
vcs.is_shallow(), OSS file checks
96-
1. versioning vcs.log() + vcs.diff_files() -> compute semver (skip unchanged D-5)
97-
2. lock update pm.lock(upgrade_package=<pkg>) for each bumped package (D-2)
98-
3. commit vcs.commit("chore(release): <umbrella_tag>") (D-1)
99-
4. tag vcs.tag() per-package tags + umbrella tag
100-
5. for each topo level:
101-
pin ──► pm.build(no_sources=True) (D-3) ──► verify ──► checksum
102-
──► pm.publish(check_url=...) (D-7) ──► pm.resolve_check() (D-9)
103-
──► registry.poll_available() ──► registry.verify_checksum()
104-
──► pm.smoke_test() ──► restore
105-
6. push vcs.push() commit + tags
106-
7. GitHub Release forge.create_release() (graceful skip, D-10)
107-
8. changelog vcs.log() + prerelease rollup mode (D-4)
108-
9. commitback vcs.commit() + vcs.push() + forge.create_pr() (optional)
133+
── STEP 1: releasekit prepare (on push to main) ──────────────────────
134+
0. preflight vcs.is_clean(), pm.lock() --check, forge.is_available() (D-10),
135+
forge.list_releases() concurrent detection (D-6),
136+
vcs.is_shallow(), OSS file checks
137+
1. versioning vcs.log(paths=[pkg.path]) -> compute semver (skip unchanged D-5)
138+
2. propagate graph.reverse_deps() -> PATCH bump for dependents (D-11)
139+
3. bump bump.bump_pyproject() for each bumped package
140+
4. lock update pm.lock(upgrade_package=<pkg>) for each bumped package (D-2)
141+
5. changelog vcs.log() + prerelease rollup mode (D-4)
142+
6. commit + push vcs.commit() on release branch, vcs.push() (D-1)
143+
7. Release PR forge.create_pr() or forge.update_pr() with embedded manifest
144+
forge.add_labels("autorelease: pending")
145+
146+
── STEP 2: releasekit tag (on Release PR merge) ──────────────────────
147+
0. find PR forge.list_prs(label="autorelease: pending", state="merged")
148+
1. parse manifest extract embedded manifest from PR body
149+
2. tag vcs.tag() per-package tags + umbrella tag on merge commit
150+
3. GitHub Release forge.create_release() (graceful skip, D-10)
151+
4. label forge.remove_labels("pending"), forge.add_labels("tagged")
152+
153+
── STEP 3: releasekit publish (on GitHub Release creation) ───────────
154+
0. checkout vcs.checkout(tag)
155+
1. for each topo level:
156+
pin ──► pm.build(no_sources=True) (D-3) ──► verify ──► checksum
157+
──► pm.publish(check_url=...) (D-7) ──► pm.resolve_check() (D-9)
158+
──► registry.poll_available() ──► registry.verify_checksum()
159+
──► pm.smoke_test() ──► restore
160+
2. label forge.add_labels("autorelease: published")
161+
3. dispatch forge.repository_dispatch() to downstream repos
109162
```
110163

111164
---
@@ -255,18 +308,20 @@ Future: Dynamic Scheduler ▼ ✅ COMPLETE
255308
│ ★ Scheduler is fully dynamic — ready for HTTP server │
256309
└───────────────────────────┬───────────────────────────────┘
257310
│
258-
Phase 5: Post-Pipeline ▼
311+
Phase 5: Release-Please ▼
259312
┌─────────────────────────────────────────────────────────┐
313+
│ prepare.py ──► versioning, graph, changelog, forge │
314+
│ (Release PR with embedded manifest) │
315+
│ release.py ──► versions, vcs, forge │
316+
│ (tag merge commit, create GitHub Release) │
260317
│ tags.py ──► config, versions, vcs, forge │
261-
│ (graceful forge.is_available() skip, D-10) │
262318
│ changelog.py ──► config, vcs (prerelease rollup, D-4) │
263319
│ release_notes.py ──► changelog, vcs, forge │
264-
│ commitback.py ──► bump, vcs, forge │
265-
│ .github/workflows/publish_python_v2.yml │
320+
│ .github/workflows/releasekit.yml (3-job pipeline) │
266321
│ │
267-
│ ✓ releasekit publish --publish-from=ci │
268-
│ ✓ Structured changelog + rich release notes │
269-
│ ✓ GitHub Releases + draft/promote │
322+
│ ✓ releasekit prepare (Release PR) │
323+
│ ✓ releasekit tag (tag + GitHub Release) │
324+
│ ✓ releasekit publish (build + upload to PyPI) │
270325
└──────────────────────────┬──────────────────────────────┘
271326
│
272327
Phase 6: UX Polish ▼
@@ -337,11 +392,12 @@ flowchart TD
337392
publisherFull["publisher.py -- full"]
338393
end
339394
340-
subgraph phase5 ["Phase 5: Post-Pipeline + CI"]
395+
subgraph phase5 ["Phase 5: Release-Please"]
396+
preparemod[prepare.py]
397+
releasemod[release.py]
341398
tagsmod[tags.py]
342399
changelogmod[changelog.py]
343400
releaseNotesmod[release_notes.py]
344-
commitbackmod[commitback.py]
345401
workflowmod[CI workflow]
346402
end
347403
@@ -410,6 +466,14 @@ flowchart TD
410466
publisherFull --> publisherBasic
411467
412468
%% Phase 5 edges
469+
preparemod --> versioningmod
470+
preparemod --> graphmod
471+
preparemod --> changelogmod
472+
preparemod --> forgemod
473+
preparemod --> vcsmod
474+
releasemod --> versionsmod
475+
releasemod --> vcsmod
476+
releasemod --> forgemod
413477
tagsmod --> configmod
414478
tagsmod --> versionsmod
415479
tagsmod --> vcsmod
@@ -419,9 +483,6 @@ flowchart TD
419483
releaseNotesmod --> changelogmod
420484
releaseNotesmod --> vcsmod
421485
releaseNotesmod --> forgemod
422-
commitbackmod --> bumpmod
423-
commitbackmod --> vcsmod
424-
commitbackmod --> forgemod
425486
426487
%% Phase 6 edges
427488
initmod --> configmod
@@ -493,7 +554,7 @@ implementations. `run_command()` logs and supports dry-run.
493554

494555
| Module | Description | Est. Lines | Actual | Status |
495556
|--------|-------------|-----------|--------|--------|
496-
| `versioning.py` | Parse Conventional Commits via `vcs.log(paths=[pkg.path])`, compute per-package semver bumps. Monorepo-aware scoping. Configurable `tag_format`. PEP 440 compliance. Skip unchanged packages (D-5). No transitive bump propagation (D-11). `--prerelease`, `--force-unchanged`. | ~220 | 361 | ✅ |
557+
| `versioning.py` | Parse Conventional Commits via `vcs.log(paths=[pkg.path])`, compute per-package semver bumps. Monorepo-aware scoping. Configurable `tag_format`. PEP 440 compliance. Skip unchanged packages (D-5). Transitive PATCH propagation to dependents via dependency graph (D-11). Supports `synchronize` (lockstep) mode. `--prerelease`, `--force-unchanged`. | ~220 | 361 | ✅ |
497558
| `pin.py` | Ephemeral `tomlkit`-based pinning. Context manager with triple-layer crash safety (atexit + SIG_DFL/os.kill + `.bak` backup). `shutil.move` atomic restore. SHA-256 verification. `packaging.Requirement` for PEP 508 dep parsing. | ~120 | 279 | ✅ |
498559
| `bump.py` | Version string rewriting in `pyproject.toml` (tomlkit, comment-preserving) and arbitrary files (`__init__.py`, constants). Regex-based with `BumpTarget(path, pattern)` config. | ~80 | 195 | ✅ |
499560
| `versions.py` | JSON version manifest. `ReleaseManifest` + `PackageVersion` dataclasses. Fail-fast on missing required fields. `bumped`/`skipped` filter properties. | ~80 | 188 | ✅ |
@@ -968,10 +1029,11 @@ py/tools/releasekit/
9681029
state.py ← run state + resume
9691030
preflight.py ← safety checks + pip-audit
9701031
publisher.py ← level-by-level orchestration
1032+
prepare.py ← Release PR creation (release-please step 1)
1033+
release.py ← Tag + GitHub Release (release-please step 2)
9711034
tags.py ← git tags + GitHub Releases
9721035
changelog.py ← structured changelog
9731036
release_notes.py ← umbrella release notes (Jinja2)
974-
commitback.py ← post-release version bump PR
9751037
ui.py ← Rich Live progress table
9761038
templates/
9771039
release_notes.md.j2 ← default release notes template
@@ -1010,7 +1072,8 @@ py/tools/releasekit/
10101072
tags_test.py
10111073
changelog_test.py
10121074
release_notes_test.py
1013-
commitback_test.py
1075+
rk_prepare_test.py
1076+
rk_release_test.py
10141077
ui_test.py
10151078
```
10161079

@@ -1027,4 +1090,75 @@ The existing release process uses:
10271090
| `py/bin/bump_version` | Bump all to same version | No per-package semver |
10281091
| `.github/workflows/publish_python.yml` | Matrix publish | No level gating |
10291092

1093+
10301094
`releasekit` replaces all four with: `uvx releasekit publish`
1095+
1096+
---
1097+
1098+
## Architecture & Data Flow
1099+
1100+
### 1. Dependency Tree Propagation (Independent Mode)
1101+
1102+
When a core package updates, the change propagates down the dependency tree to ensure all consumers are tested and pinned against the new version.
1103+
1104+
```text
1105+
[genkit] v0.5.0 → v0.6.0 (Minor Bump: "feat: core update")
1106+
│
1107+
▼
1108+
[genkit-plugin-vertex-ai]
1109+
Depends on: genkit
1110+
Action: v0.5.0 → v0.5.1 (Patch Bump)
1111+
Reason: "dependency genkit bumped"
1112+
│
1113+
▼
1114+
[sample-app]
1115+
Depends on: genkit-plugin-vertex-ai
1116+
Action: v0.1.0 → v0.1.1 (Patch Bump)
1117+
Reason: "dependency genkit-plugin-vertex-ai bumped"
1118+
```
1119+
1120+
### 2. Release Lifecycle
1121+
1122+
The 3-stage process separates planning, tagging, and publishing.
1123+
1124+
```text
1125+
Developer
1126+
│
1127+
│ pushes to main
1128+
▼
1129+
┌───────────────────────────────────────────────────────────────┐
1130+
│ STEP 1: PREPARE (releasekit prepare) │
1131+
│ │
1132+
│ 1. Scan commits per package │
1133+
│ 2. Compute bumps + Propagate to dependents │
1134+
│ 3. Update pyproject.toml & uv.lock │
1135+
│ 4. Generate Changelogs │
1136+
│ 5. Create/Update "Release PR" (autorelease: pending) │
1137+
└───────────────────────────────────────────────────────────────┘
1138+
│
1139+
│ merges Release PR
1140+
▼
1141+
┌───────────────────────────────────────────────────────────────┐
1142+
│ STEP 2: TAG (releasekit tag) │
1143+
│ │
1144+
│ 1. Find merged PR with "autorelease: pending" │
1145+
│ 2. Parse Manifest from PR Body │
1146+
│ 3. Tag Merge Commit (pkg-v1.0 + py-v1.0) │
1147+
│ 4. Create GitHub Release │
1148+
│ 5. Label PR "autorelease: tagged" │
1149+
└───────────────────────────────────────────────────────────────┘
1150+
│
1151+
│ triggered by Release creation
1152+
▼
1153+
┌───────────────────────────────────────────────────────────────┐
1154+
│ STEP 3: PUBLISH (releasekit publish) │
1155+
│ │
1156+
│ 1. Checkout Tag │
1157+
│ 2. Rewrite deps in pyproject.toml (Ephemeral Pinning) │
1158+
│ 3. Build Wheels/Sdists │
1159+
│ 4. Upload to PyPI │
1160+
│ 5. Label PR "autorelease: published" │
1161+
│ 6. Dispatch "repository_dispatch" to Plugins Repos │
1162+
└───────────────────────────────────────────────────────────────┘
1163+
```
1164+

0 commit comments

Comments
 (0)