feat(workspace): adopt independent package versioning policy by josecelano · Pull Request #1961 · torrust/torrust-tracker

josecelano · 2026-06-29T18:42:47Z

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:

Issue spec with three-tier versioning model (tracker runtime / API contract / platform-utility / unpublished tooling), release process implications, and Appendix A with version assignment table per crate
ADR (20260629000000) documenting the independent versioning decision, alternatives considered, and rationale
EPIC and DECISIONS log updated with references
.github/workflows/deployment.yaml — refined to publish only torrust-tracker
.github/workflows/deployment-packages.yaml — new workflow for per-package publishing
docs/release_process.md — split into two paths (tracker release + per-package publish)

✅ Phase 2 — Version Migration (completed)

✅ Removed version.workspace = true from all 26 Cargo.toml manifests
✅ Set explicit initial versions per Appendix A:
- 4 crates keep 3.0.0 (already on crates.io)
- 23 crates start at 0.1.0
- Root binary keeps 3.0.0-develop
✅ Removed version from [workspace.package] in root Cargo.toml
✅ Updated all inter-package dependency version references
✅ Regenerated Cargo.lock for consistency
✅ cargo check --workspace passes
✅ linter all passes
✅ cargo test --doc --workspace passes

✅ Phase 3 — CI/Release Refinements (completed)

Any remaining polish after Phase 2 is committed.

Key Decisions

All packages version independently — path dependencies guarantee workspace compatibility regardless of declared version numbers
Two-concept release model: tracker application release (releases/v*) and per-package publish (releases/pkg/<crate>/v<semver>)
Glob safety: releases/v* does NOT match releases/pkg/... in GitHub Actions
Version by namespace for public contracts (REST API v1/ modules, config v2_0_0/)
4 crates never published (e2e-tools, persistence-benchmark, torrent-repository-benchmarking, workspace-coupling)

Verification

linter all passes
cargo test --doc --workspace passes
cargo +nightly fmt --check passes
cargo +nightly check --tests --benches --examples --workspace --all-targets --all-features passes
cargo +stable test --tests --benches --examples --workspace --all-targets --all-features passes
GPG-signed commits (all 5 commits)
cargo check --workspace passes with new versions
All 21 Copilot review comments addressed
All 27 files changed (292 insertions, 439 deletions)

Copilot

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-tracker and 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.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 4 comments.

Define and document the policy that all workspace packages version independently, replacing the implicit shared workspace version. Includes: - Issue spec with four-tier versioning model and Appendix A - ADR documenting the decision - EPIC and DECISIONS log updates - CI workflows (deployment-packages.yaml, deployment.yaml) - Release process documentation update - Branch format validation and output injection protection - Secret scoping and review feedback from all rounds

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 - Published crates (4): 3.0.0 (primitives, configuration, test-helpers) - Unpublished crates (23): 0.1.0 - Removed version from [workspace.package] - Updated all inter-package dependency version references - Set publish = false for unpublished tooling crates - Regenerated Cargo.lock for consistency

Copilot

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 1 comment.

josecelano · 2026-07-01T08:25:42Z

ACK f82f49a

josecelano temporarily deployed to coverage June 29, 2026 18:42 — with GitHub Actions Inactive

josecelano requested review from Copilot and da2ce7 June 29, 2026 18:44

Copilot started reviewing on behalf of josecelano June 29, 2026 18:44 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

josecelano force-pushed the 1926-1669-si-32-define-package-versioning-strategy branch from a88721d to 4cb1889 Compare June 30, 2026 06:59

josecelano temporarily deployed to coverage June 30, 2026 06:59 — with GitHub Actions Inactive

josecelano requested a review from Copilot June 30, 2026 07:24

Copilot started reviewing on behalf of josecelano June 30, 2026 07:25 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

josecelano temporarily deployed to coverage June 30, 2026 08:23 — with GitHub Actions Inactive

josecelano requested a review from Copilot June 30, 2026 08:36

josecelano self-assigned this Jun 30, 2026

Copilot started reviewing on behalf of josecelano June 30, 2026 08:36 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

josecelano temporarily deployed to coverage June 30, 2026 09:04 — with GitHub Actions Inactive

josecelano temporarily deployed to coverage June 30, 2026 10:05 — with GitHub Actions Inactive

josecelano force-pushed the 1926-1669-si-32-define-package-versioning-strategy branch from 26de059 to 8fed65f Compare June 30, 2026 15:12

josecelano temporarily deployed to coverage June 30, 2026 15:12 — with GitHub Actions Inactive

josecelano had a problem deploying to coverage June 30, 2026 16:01 — with GitHub Actions Failure

josecelano requested a review from Copilot June 30, 2026 16:02

Copilot started reviewing on behalf of josecelano June 30, 2026 16:02 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread .github/workflows/deployment-packages.yaml

Comment thread .github/workflows/deployment-packages.yaml Outdated

Comment thread .github/workflows/deployment-packages.yaml

Comment thread docs/adrs/20260629000000_adopt_independent_package_versioning.md Outdated

josecelano had a problem deploying to coverage June 30, 2026 16:39 — with GitHub Actions Failure

josecelano had a problem deploying to coverage June 30, 2026 19:20 — with GitHub Actions Failure

josecelano had a problem deploying to coverage June 30, 2026 20:07 — with GitHub Actions Failure

josecelano force-pushed the 1926-1669-si-32-define-package-versioning-strategy branch from 4ed094b to 8d1db13 Compare June 30, 2026 21:49

josecelano temporarily deployed to coverage June 30, 2026 21:49 — with GitHub Actions Inactive

josecelano requested a review from Copilot June 30, 2026 21:49

Copilot started reviewing on behalf of josecelano June 30, 2026 21:52 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread packages/rest-api-client/Cargo.toml Outdated

Comment thread .github/workflows/deployment.yaml Outdated

Comment thread .github/workflows/deployment-packages.yaml Outdated

Comment thread .github/workflows/deployment-packages.yaml

josecelano temporarily deployed to coverage July 1, 2026 06:50 — with GitHub Actions Inactive

josecelano added 2 commits July 1, 2026 08:19

josecelano force-pushed the 1926-1669-si-32-define-package-versioning-strategy branch from da13b1e to b24149f Compare July 1, 2026 07:33

josecelano temporarily deployed to coverage July 1, 2026 07:33 — with GitHub Actions Inactive

josecelano requested a review from Copilot July 1, 2026 07:38

Copilot started reviewing on behalf of josecelano July 1, 2026 07:39 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread .github/workflows/deployment-packages.yaml Outdated

josecelano marked this pull request as ready for review July 1, 2026 08:13

josecelano requested a review from a team as a code owner July 1, 2026 08:13

fix: add --all-targets --all-features to per-package publish test step

f82f49a

josecelano deployed to coverage July 1, 2026 08:25 — with GitHub Actions Active

Uh oh!

Conversation

josecelano commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Phase Progress

✅ Phase 1 — Policy Definition (committed)

✅ Phase 2 — Version Migration (completed)

✅ Phase 3 — CI/Release Refinements (completed)

Key Decisions

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

josecelano commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

josecelano commented Jun 29, 2026 •

edited

Loading