feat(workspace): adopt independent package versioning policy#1961
Draft
josecelano wants to merge 6 commits into
Draft
feat(workspace): adopt independent package versioning policy#1961josecelano wants to merge 6 commits into
josecelano wants to merge 6 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR documents and codifies a shift from lockstep workspace versioning to independent per-crate versioning, including corresponding release/publish workflow documentation and CI workflow split for tracker vs. per-package publishing.
Changes:
- Adds an ADR and updates EPIC/decision logs to formally adopt independent versioning for workspace crates.
- Updates the tracker deployment workflow to publish only
torrust-trackerand introduces a new workflow for publishing individual workspace packages. - Extends release-process documentation to include a per-package publishing path and updates project spellcheck dictionary.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| project-words.txt | Adds new dictionary terms for cspell. |
| docs/release_process.md | Documents the split release model (tracker release vs. per-package publish). |
| docs/issues/open/1926-1669-si-32-define-package-versioning-strategy.md | Updates the issue spec with the independent-versioning policy and related process details. |
| docs/issues/open/1669-overhaul-packages/EPIC.md | Links the EPIC to the new ADR/issue and updates versioning-policy narrative. |
| docs/issues/open/1669-overhaul-packages/DECISIONS.md | Adds DEC-16 documenting adoption of independent package versioning. |
| docs/adrs/index.md | Registers the new ADR in the ADR index. |
| docs/adrs/20260629000000_adopt_independent_package_versioning.md | New ADR describing the independent-versioning policy and release model split. |
| docs/adrs/20260623200526_adopt_contract-first_architecture_for_rest_api.md | Adds a reference to the new ADR for “version by namespace” rationale. |
| .github/workflows/deployment.yaml | Narrows tracker deployment to releases/v* and publishes only torrust-tracker. |
| .github/workflows/deployment-packages.yaml | New workflow to publish a single crate based on releases/pkg/** branches or manual dispatch. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
josecelano
force-pushed
the
1926-1669-si-32-define-package-versioning-strategy
branch
from
a88721d to
4cb1889
Compare
Comment on lines
760
to
762
| See the ADR for full details, including the two-concept release model split | ||
| (tracker application release vs individual package publish). | ||
| migration does not run ahead of layer decoupling. |
Member
Author
There was a problem hiding this comment.
Fixed in 5db2060. Removed the orphaned sentence fragment "migration does not run ahead of layer decoupling." from EPIC.md.
Comment on lines
+250
to
+252
| > All dependency crates are published independently via `deployment-packages.yaml` as they | ||
| > evolve. This avoids conflating versioning semantics (three-tier model) with publish | ||
| > mechanics (single workflow per package). |
Member
Author
There was a problem hiding this comment.
Fixed in 5db2060. The Design decision callout now references "four-tier model" consistently instead of "three-tier model".
Comment on lines
+760
to
763
| See the ADR for full details, including the two-concept release model split | ||
| (tracker application release vs individual package publish). | ||
| migration does not run ahead of layer decoupling. | ||
|
|
Member
Author
There was a problem hiding this comment.
Fixed in 5db2060. Removed the orphaned sentence fragment from EPIC.md.
Define and document the policy that all workspace packages version independently, replacing the implicit shared workspace version. Phase 1 of issue torrust#1926 (SI-32). Includes: - Issue spec with three-tier versioning model and Appendix A - ADR documenting the decision - EPIC and DECISIONS log updates - CI workflows (deployment-packages.yaml, deployment.yaml updates) - Release process documentation update
Phase 2 of issue torrust#1926 (SI-32). Remove version.workspace = true from all 26 workspace Cargo.toml manifests and set explicit versions per the approved version assignment table (Appendix A in issue spec). Key changes: - Root torrust-tracker binary: 3.0.0-develop (own explicit field) - Published crates (4): 3.0.0 (primitives, configuration, test-helpers) - Unpublished crates (23): 0.1.0 - Removed version from [workspace.package] in root Cargo.toml - Updated all inter-package dependency version references - Regenerated Cargo.lock for consistency
Fix 5 issues from the Phase 2 Copilot review:
- Fix "three-tier model" references to "four-tier model" with "publishable" wording
- Fix "still publish the bundle" to "now publish only torrust-tracker"
- Remove orphaned sentence fragment in EPIC.md ("migration does not run...")
- Fix output injection in deployment-packages.yaml via env + printf pattern
- Comment about Goal section resolved by Phase 2 implementation itself
Unpublished tooling crates should not inherit publish.workspace = true.
josecelano
force-pushed
the
1926-1669-si-32-define-package-versioning-strategy
branch
from
26de059 to
8fed65f
Compare
Comment on lines
+58
to
+60
| if [ -n "$INPUT_CRATE_NAME" ]; then | ||
| printf 'crate-name=%s\n' "$INPUT_CRATE_NAME" >> "$GITHUB_OUTPUT" | ||
| else |
Comment on lines
+43
to
+45
| env: | ||
| CARGO_REGISTRY_TOKEN: "${{ secrets.TORRUST_UPDATE_CARGO_REGISTRY_TOKEN }}" | ||
|
|
Comment on lines
+106
to
+110
| publish: | ||
| name: Publish | ||
| environment: deployment | ||
| needs: [extract-crate, test] | ||
| runs-on: ubuntu-latest |
Comment on lines
+52
to
+53
| | **Platform/utility** | Crate's own library API changed | `test-helpers`, `e2e-tools` | | ||
| | **Unpublished tooling** | Version changes only when internal API changes meaningfully | `persistence-benchmark`, `workspace-coupling` | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Define and implement a SemVer policy for all workspace packages, replacing the implicit "everything shares one workspace version" with independent versioning for every crate.
Issue: #1926 (SI-32) — subissue of EPIC #1669 (Overhaul: Packages)
Phase Progress
✅ Phase 1 — Policy Definition (committed)
All policy definition work is complete and ready for review:
20260629000000) documenting the independent versioning decision, alternatives considered, and rationale.github/workflows/deployment.yaml— refined to publish onlytorrust-tracker.github/workflows/deployment-packages.yaml— new workflow for per-package publishingdocs/release_process.md— split into two paths (tracker release + per-package publish)✅ Phase 2 — Version Migration (completed)
version.workspace = truefrom all 26Cargo.tomlmanifests3.0.0(already on crates.io)0.1.03.0.0-developversionfrom[workspace.package]in rootCargo.tomlCargo.lockfor consistencycargo check --workspacepasseslinter allpassescargo test --doc --workspacepasses✅ Phase 3 — CI/Release Refinements (completed)
Any remaining polish after Phase 2 is committed.
Key Decisions
releases/v*) and per-package publish (releases/pkg/<crate>/v<semver>)releases/v*does NOT matchreleases/pkg/...in GitHub Actionsv1/modules, configv2_0_0/)e2e-tools,persistence-benchmark,torrent-repository-benchmarking,workspace-coupling)Verification
linter allpassescargo test --doc --workspacepassescargo +nightly fmt --checkpassescargo +nightly check --tests --benches --examples --workspace --all-targets --all-featurespassescargo +stable test --tests --benches --examples --workspace --all-targets --all-featurespassescargo check --workspacepasses with new versions