@@ -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 │
272327Phase 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