Skip to content

docs: add release process pointing to the Tracker's source of truth #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
josecelano merged 1 commit into from
Nov 10, 2026
Merged

docs: add release process pointing to the Tracker's source of truth #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Common functionality used in all Torrust HTTP servers.

[Crate documentation](https://docs.rs/torrust-server-lib).

[Release process](docs/release_process.md).

## License

The project is licensed under the terms of the [GNU AFFERO GENERAL PUBLIC LICENSE](./LICENSE).
21 changes: 21 additions & 0 deletions docs/release_process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Release process

This repository holds a single publishable crate, `torrust-server-lib`.

The process is the one defined for workspace packages in the Torrust Tracker, which is the source
of truth. Follow its
[Publishing a Workspace Package](https://github.com/torrust/torrust-tracker/blob/develop/docs/release_process.md#publishing-a-workspace-package)
section (versioning, changelog, dry run, publish, signed tag). Do not copy it here.

@da2ce7 da2ce7 Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Minor][F1] The parenthetical lists steps the linked section does not contain.

The tracker's docs/release_process.md at develop never mentions a changelog (no match anywhere in the file), and its only versioning content is "own explicit version field (not version.workspace = true)", a workspace concern. The tag command exists only in step 5 of the Automated Workflow, which line 13 rules out. A maintainer who follows the link for these steps finds none of them on the path that applies; the changelog and tag steps live only in the checklist below. Suggest naming what the section actually supplies here (test, dry run, publish, the tag form) and saying that the changelog and tag steps are local.


## Differences in this repository

- There is no `develop` branch: releases are cut from `main`.

@da2ce7 da2ce7 Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nit][F3] ci.yaml still names a develop branch.

The default branch is main and every merge in the history targets it, so the claim holds for releases, but .github/workflows/ci.yaml lines 3, 9 and 11 trigger on [main, develop]. A reader checking the claim against CI meets the opposite; dropping develop from the workflow in a follow-up would make the two agree.

- There is no `deployment-packages.yaml` workflow and no `releases/pkg/**` branches, so the
**manual fallback** of the Tracker document is the only path.

@da2ce7 da2ce7 Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Minor][F2] The manual fallback named as the only path publishes without a tag.

The tracker's Manual Fallback opens with "If CI is unavailable or you need to publish without creating a Git reference" and has four steps: explicit version, cargo test, dry run, publish. Read with the link, this line yields a release with no tag; only checklist step 3 adds one. Suggest saying here that the tag step is taken from the Automated Workflow's step 5, with the tag name from line 15.

- The tag is `v<semver>` (for example `v0.6.0`), not `pkg/<crate-name>/v<semver>`.

@da2ce7 da2ce7 Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nit][F4] v0.6.0 is given as an example tag, but this repository has no tags and no releases.

No version from 0.1.0 to 0.6.0 is tagged, so the v<semver> form is introduced here rather than described. Suggest stating it as the convention from the next tag on, or tagging v0.6.0 on the commit 0.6.0 is published from, so a reader does not look for an existing tag to copy.


## Checklist

1. Merge a PR that bumps `version` in `Cargo.toml` and adds the `CHANGELOG.md` entry.
2. From the merged `main`: `cargo publish --dry-run`, then `cargo publish`.

@da2ce7 da2ce7 Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nit][F5] The checklist drops the source's test step and partly restates the source.

The Manual Fallback's step 2 is cargo test -p <crate-name>; checklist step 2 goes straight to the dry run. ci.yaml runs cargo test --workspace on every push to main (lines 8–9 and 61–63), so the local equivalent is "CI is green on the merged main commit"; naming one of the two would close the gap. Line 8 also says not to copy the source and the issue asks for differences only, while this section restates a short form of it; it should either stay differences-only or be complete.

3. Create the signed tag on the published commit and push it to `torrust/torrust-server-lib`.
Comment on lines +17 to +21

@da2ce7 da2ce7 Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Suggestion][F6] Name the workspace-only source steps that do not apply and the cross-repository step that replaces them.

The source's "own explicit version field" step, the Automated Workflow's step 6 (update the workspace root Cargo.toml dependency entry) and the dependency-order note only make sense inside the tracker workspace. Their counterpart here is downstream: the tracker at develop pins torrust-server-lib = "0.5.0" from crates.io in its root Cargo.toml (line 115) and in five package manifests (axum-health-check-api-server, axum-http-server, axum-rest-api-server, axum-server, udp-server). A step 4, bumping that dependency in a tracker pull request, would close the loop.

Loading