Skip to content

Commit 2bfac5b

Browse files
josecelanojosecelano
committed
docs(issues): add specs for issues torrust#1786 and torrust#1787
- torrust#1786: migrate lint config to [workspace.lints] in Cargo.toml - torrust#1787: evaluate and update workspace MSRV above 1.85 (blocked on torrust#1669) Add `callsites` to cspell dictionary (used in torrust#1786 spec).
1 parent e3cc483 commit 2bfac5b

3 files changed

Lines changed: 368 additions & 0 deletions

File tree

‎docs/issues/open/1786-tighten-lint-config.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
doc-type: issue
3+
issue-type: task
4+
status: open
5+
priority: p2
6+
github-issue: 1786
7+
spec-path: docs/issues/open/1786-tighten-lint-config.md
8+
branch: "1786-tighten-lint-config"
9+
related-pr: 1784
10+
last-updated-utc: 2026-05-15 08:00
11+
semantic-links:
12+
skill-links:
13+
- create-issue
14+
related-artifacts:
15+
- Cargo.toml
16+
- .cargo/config.toml
17+
---
18+
19+
<!-- skill-link: create-issue -->
20+
21+
# Issue #1786 - Migrate lint configuration to `[workspace.lints]` in Cargo.toml
22+
23+
## Goal
24+
25+
Replace the ad-hoc lint configuration spread across `.cargo/config.toml` RUSTFLAGS and
26+
`torrust-linting` command-line arguments with a single authoritative `[workspace.lints]`
27+
section in `Cargo.toml`, following the idiomatic Cargo approach used in `torrust-index`.
28+
29+
## Background
30+
31+
Lint enforcement is currently split across three places:
32+
33+
1. **`.cargo/config.toml` RUSTFLAGS** — carries rust-group denials (`-D warnings`,
34+
`-D future-incompatible`, `-D rust-2018-idioms`, etc.). These apply to every cargo
35+
invocation (build, test, check) but are invisible without reading the config file.
36+
37+
2. **`torrust-linting` clippy runner** — passes `-D clippy::correctness`,
38+
`-D clippy::suspicious`, `-D clippy::complexity`, `-D clippy::perf`,
39+
`-D clippy::style`, `-D clippy::pedantic` on the command line. These are only
40+
active when the linter tool runs; `cargo clippy` invoked directly does not
41+
apply them.
42+
43+
3. **`[lints.clippy]` on the root `[package]`** — the root `Cargo.toml` already has a
44+
`[lints.clippy]` section for the main binary package only; this is _not_ a
45+
`[workspace.lints]` and does not propagate to other workspace members. It also
46+
contains `needless_return = "allow"` with a `# temp allow this lint` comment,
47+
suggesting it was added as a temporary workaround rather than a deliberate policy
48+
decision. The original reason and whether the underlying callsites have since been
49+
fixed is unknown; this must be investigated before the section is migrated or removed.
50+
51+
This fragmentation was raised in PR #1784 review by @da2ce7, who referenced the
52+
`torrust-index` configuration as the target state.
53+
54+
Cargo 1.64+ supports `[workspace.lints]`, the idiomatic way to declare workspace-wide
55+
lint policy in a single, visible, version-controlled location.
56+
57+
## Scope
58+
59+
### In Scope
60+
61+
- Add `[workspace.lints.rust]` to the root `Cargo.toml` with the lint groups currently
62+
expressed as RUSTFLAGS.
63+
- Add `[workspace.lints.clippy]` to the root `Cargo.toml` with the clippy groups
64+
currently passed by `torrust-linting`, plus `nursery = "warn"` as suggested in the
65+
PR review.
66+
- Remove the now-redundant lint entries from `RUSTFLAGS` in `.cargo/config.toml`.
67+
- Remove the root `[lints.clippy]` package-level section (superseded by workspace lints).
68+
- Fix any new warnings or errors that surface once `nursery = "warn"` and
69+
`all = "deny"` take effect (expected to be small; most lints are already enforced).
70+
- Investigate the `needless_return = "allow"` entry (see T7 below) and resolve it.
71+
- Coordinate with `torrust-linting`: either remove the redundant `-D clippy::X` flags
72+
from the clippy runner (cleaner) or document that they are intentional redundancy
73+
(safety net). A follow-up PR to `torrust-linting` may be needed.
74+
75+
### Out of Scope
76+
77+
- Changes to any other lint policy beyond migrating the existing set.
78+
- Enabling additional deny-level lints beyond what is listed in the Background section.
79+
- Changes to `torrust-linting` beyond removing the now-redundant clippy group flags.
80+
- MSRV changes (tracked separately in #1787).
81+
82+
## Implementation Plan
83+
84+
Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
85+
86+
| ID | Status | Task | Notes / Expected Output |
87+
| --- | ------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
88+
| T1 | TODO | Add `[workspace.lints.rust]` to root `Cargo.toml` | Mirrors current RUSTFLAGS entries; `rust-2024-compatibility` added |
89+
| T2 | TODO | Add `[workspace.lints.clippy]` to root `Cargo.toml` | Matches torrust-index config; `nursery = "warn"`, `all = "deny"` |
90+
| T3 | TODO | Remove redundant RUSTFLAGS lint entries from `.cargo/config.toml` | Only lint-related entries removed; other rustflags (e.g. `-D unused`) migrated too |
91+
| T4 | TODO | Remove root `[lints.clippy]` package section from `Cargo.toml` | Superseded by `[workspace.lints.clippy]` |
92+
| T5 | TODO | Fix any new lint failures from `nursery = "warn"` / `all = "deny"` | `cargo clippy --workspace --all-targets --all-features` must pass cleanly |
93+
| T6 | TODO | Update `torrust-linting` to remove redundant `-D clippy::X` flags | Open a separate PR in `torrust-linting`; document decision if deferred |
94+
| T7 | TODO | Investigate and resolve `needless_return = "allow"` in `Cargo.toml` | See Background; decide: fix callsites and remove the allow, or keep it with documented rationale |
95+
| T8 | TODO | Verify all quality gates pass | `linter all`, doc tests, full test suite, pre-push hook |
96+
97+
## Progress Tracking
98+
99+
### Workflow Checkpoints
100+
101+
- [ ] Spec drafted in `docs/issues/drafts/`
102+
- [x] Spec reviewed and approved by user/maintainer
103+
- [x] GitHub issue created and issue number added to this spec
104+
- [ ] Implementation completed
105+
- [ ] Automatic verification completed (`linter all`, relevant tests, and pre-push checks)
106+
- [ ] Manual verification scenarios executed and recorded (status + evidence)
107+
- [ ] Acceptance criteria reviewed after implementation and updated with evidence
108+
- [ ] Reviewer validated acceptance criteria and updated checkboxes
109+
- [ ] Committer verified spec progress is up to date before commit
110+
- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`
111+
112+
### Progress Log
113+
114+
- 2026-05-15 07:00 UTC - Agent - Spec drafted, triggered by @da2ce7 review comment on PR #1784
115+
- 2026-05-15 08:00 UTC - Agent - GitHub issue #1786 created; spec moved from drafts/ to open/
116+
117+
## Acceptance Criteria
118+
119+
- [ ] AC1: `[workspace.lints.rust]` in `Cargo.toml` covers all groups previously in RUSTFLAGS
120+
- [ ] AC2: `[workspace.lints.clippy]` in `Cargo.toml` covers all groups previously passed by `torrust-linting`, plus `nursery = "warn"` and `all = "deny"`
121+
- [ ] AC3: `.cargo/config.toml` no longer contains lint-related RUSTFLAGS entries
122+
- [ ] AC4: The root package `[lints.clippy]` section is removed
123+
- [ ] AC5: `cargo clippy --workspace --all-targets --all-features` exits `0` with no warnings
124+
- [ ] AC6: `linter all` exits `0`
125+
- [ ] AC7: All tests pass (`cargo test --workspace --all-targets --all-features`)
126+
- [ ] AC8: Pre-push hook passes
127+
- [ ] AC9: The `needless_return` allow is either removed (callsites fixed) or kept with a documented rationale replacing the `# temp allow this lint` comment
128+
- [ ] AC10: Manual verification scenarios are executed and documented (status + evidence)
129+
- [ ] AC11: Acceptance criteria are re-reviewed after implementation and reflect actual behavior
130+
131+
## Verification Plan
132+
133+
### Automatic Checks
134+
135+
- `linter all`
136+
- `cargo clippy --workspace --all-targets --all-features`
137+
- `cargo test --doc --workspace`
138+
- `cargo test --tests --benches --examples --workspace --all-targets --all-features`
139+
- Pre-push hook (full gate)
140+
141+
### Manual Verification Scenarios
142+
143+
Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`.
144+
145+
| ID | Scenario | Command/Steps | Expected Result | Status | Evidence |
146+
| --- | ------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- | ------ | -------- |
147+
| M1 | Direct `cargo clippy` enforces workspace lints without linter | `cargo clippy --workspace --all-targets --all-features` | Exits 0; pedantic/nursery lints applied | TODO | |
148+
| M2 | `cargo build` no longer picks up redundant lint RUSTFLAGS | `cargo build --workspace` (inspect output for lint warnings) | No spurious warnings from removed RUSTFLAGS | TODO | |
149+
| M3 | `linter all` still passes with the new configuration | `linter all` | Exits 0 | TODO | |
150+
151+
### Acceptance Verification
152+
153+
| AC ID | Status (`TODO`/`DONE`) | Evidence |
154+
| ----- | ---------------------- | -------- |
155+
| AC1 | TODO | |
156+
| AC2 | TODO | |
157+
| AC3 | TODO | |
158+
| AC4 | TODO | |
159+
| AC5 | TODO | |
160+
| AC6 | TODO | |
161+
| AC7 | TODO | |
162+
| AC8 | TODO | |
163+
| AC9 | TODO | |
164+
| AC10 | TODO | |
165+
| AC11 | TODO | |
166+
167+
## Risks and Trade-offs
168+
169+
- **`nursery = "warn"` may surface many warnings**: nursery lints are experimental and
170+
can be noisy. Fixing them is not mandatory for CI to pass (warn, not deny), but a
171+
large warning count degrades signal quality. Monitor after enabling.
172+
- **`torrust-linting` coordination**: if the redundant `-D` flags are left in the linter
173+
after workspace lints are added, they remain harmless (idempotent) but add confusion.
174+
Cleaning them up requires a separate PR to `torrust-linting`.
175+
176+
## References
177+
178+
- Related PRs: #1784
179+
- Suggested by: @da2ce7 in PR #1784 review
180+
- Reference config: `torrust-index` workspace `Cargo.toml`
181+
- Related issue: #1787 (evaluate MSRV bump)

‎docs/issues/open/1787-evaluate-msrv-bump.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
doc-type: issue
3+
issue-type: task
4+
status: blocked
5+
priority: p2
6+
github-issue: 1787
7+
spec-path: docs/issues/open/1787-evaluate-msrv-bump.md
8+
branch: "1787-evaluate-msrv-bump"
9+
related-pr: 1784
10+
last-updated-utc: 2026-05-15 08:00
11+
blocked-by: "#1669 (package restructuring)"
12+
semantic-links:
13+
skill-links:
14+
- create-issue
15+
related-artifacts:
16+
- Cargo.toml
17+
- AGENTS.md
18+
- .github/skills/dev/maintenance/setup-dev-environment/SKILL.md
19+
---
20+
21+
<!-- skill-link: create-issue -->
22+
23+
# Issue #1787 - Evaluate and update workspace MSRV above 1.85
24+
25+
## Goal
26+
27+
Decide on the appropriate Minimum Supported Rust Version (MSRV) for the workspace
28+
given the project's trajectory (planned extraction of `bittorrent-*` crates as
29+
independent libraries) and update `rust-version` in `Cargo.toml` accordingly.
30+
31+
## Background
32+
33+
PR #1784 set `rust-version = "1.85"` — the strict minimum required to compile
34+
Rust edition 2024. This was correct as the conservative baseline for the migration,
35+
but 1.85 is now several releases behind the current stable toolchain.
36+
37+
Two classes of crate coexist in this workspace:
38+
39+
1. **Application layer** (`torrust-tracker-*` crates and the main binary) — not
40+
consumed as a library by external projects; MSRV has no downstream impact.
41+
42+
2. **Protocol/domain layer** (`bittorrent-*` crates: `bittorrent-peer-id`,
43+
`bittorrent-http-tracker-protocol`, `bittorrent-udp-tracker-protocol`,
44+
`bittorrent-tracker-core`, `bittorrent-http-tracker-core`,
45+
`bittorrent-udp-tracker-core`, `bittorrent-tracker-client`) — planned for
46+
extraction into independent repositories and publication to crates.io, where
47+
they will be consumed by other BitTorrent projects.
48+
49+
This dual nature creates a tension:
50+
51+
- **For the application layer**: there is no reason to stay on an old MSRV; tracking
52+
a recent stable is better (access to new APIs, better diagnostics).
53+
- **For the future libraries**: a conservative MSRV (e.g. latest stable minus two
54+
releases, or a deliberate policy) is appropriate once they are published.
55+
56+
Until the `bittorrent-*` crates are extracted, a single workspace MSRV applies to
57+
both classes, so the decision must be made with the extraction timeline in mind.
58+
59+
**This issue is currently blocked on #1669** (ongoing package restructuring).
60+
Several decisions that directly affect the MSRV strategy have not yet been made:
61+
62+
- Which packages will be extracted as independent crates.io libraries.
63+
- Final names for those packages.
64+
- Which packages will share a versioning lifecycle with the main tracker and which
65+
will evolve independently.
66+
- Publication targets and minimum toolchain expectations for downstream consumers.
67+
68+
The MSRV evaluation should be re-opened only after #1669 has settled these questions.
69+
Opening it sooner risks choosing a policy that becomes invalid once extraction scope
70+
is defined.
71+
72+
## Scope
73+
74+
### In Scope
75+
76+
- Evaluate the appropriate MSRV policy for this workspace given the two crate classes.
77+
- Define a policy: track latest stable, pin to a specific recent release, or maintain
78+
a conservative floor.
79+
- Update `rust-version` in `Cargo.toml` to the agreed value.
80+
- Update all documentation that references the MSRV:
81+
- `AGENTS.md` (line referencing `MSRV 1.85`)
82+
- `.github/skills/dev/maintenance/setup-dev-environment/SKILL.md`
83+
- Verify CI passes with the new MSRV value.
84+
85+
### Out of Scope
86+
87+
- Extracting `bittorrent-*` crates to independent repositories (separate epic).
88+
- Setting per-crate MSRV values (only the workspace `rust-version` is in scope here).
89+
- Adding a MSRV CI job (may be proposed as a follow-up if a conservative MSRV is chosen).
90+
91+
## Blockers
92+
93+
- **#1669 — Package restructuring**: names, extraction scope, versioning lifecycle, and
94+
publication targets for the `bittorrent-*` crates must be decided before a rational
95+
MSRV policy can be set. Track that issue and re-evaluate when it closes.
96+
97+
## Implementation Plan
98+
99+
Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
100+
101+
| ID | Status | Task | Notes / Expected Output |
102+
| --- | ------ | ------------------------------------------------------------------- | ------------------------------------------------------ |
103+
| T1 | TODO | Decide MSRV policy (track latest stable vs. pin conservative floor) | Document the rationale in this spec before proceeding |
104+
| T2 | TODO | Update `rust-version` in root `Cargo.toml` | Change from `"1.85"` to the agreed value |
105+
| T3 | TODO | Update `AGENTS.md` MSRV reference | Keep in sync with `Cargo.toml` |
106+
| T4 | TODO | Update setup-dev-environment SKILL.md MSRV reference | Keep in sync with `Cargo.toml` |
107+
| T5 | TODO | Verify CI passes | Full quality gate (`linter all`, tests, pre-push hook) |
108+
109+
## Progress Tracking
110+
111+
### Workflow Checkpoints
112+
113+
- [ ] Spec drafted in `docs/issues/drafts/`
114+
- [x] Spec reviewed and approved by user/maintainer
115+
- [x] GitHub issue created and issue number added to this spec
116+
- [ ] Implementation completed
117+
- [ ] Automatic verification completed (`linter all`, relevant tests, and pre-push checks)
118+
- [ ] Manual verification scenarios executed and recorded (status + evidence)
119+
- [ ] Acceptance criteria reviewed after implementation and updated with evidence
120+
- [ ] Reviewer validated acceptance criteria and updated checkboxes
121+
- [ ] Committer verified spec progress is up to date before commit
122+
- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`
123+
124+
### Progress Log
125+
126+
- 2026-05-15 07:00 UTC - Agent - Spec drafted, follow-up from PR #1784 (Rust edition 2024 migration, MSRV set to 1.85)
127+
- 2026-05-15 07:30 UTC - Jose Celano - Marked blocked on #1669 (package restructuring); MSRV policy requires knowing extraction scope, names, and versioning lifecycle
128+
- 2026-05-15 08:00 UTC - Agent - GitHub issue #1787 created; spec moved to docs/issues/open/
129+
130+
## Acceptance Criteria
131+
132+
- [ ] AC1: A MSRV policy decision is recorded in this spec with rationale
133+
- [ ] AC2: `rust-version` in `Cargo.toml` reflects the agreed value
134+
- [ ] AC3: `AGENTS.md` MSRV reference is in sync with `Cargo.toml`
135+
- [ ] AC4: `setup-dev-environment` SKILL.md MSRV reference is in sync with `Cargo.toml`
136+
- [ ] AC5: `linter all` exits `0`
137+
- [ ] AC6: All tests pass
138+
- [ ] AC7: Pre-push hook passes
139+
140+
## Verification Plan
141+
142+
### Automatic Checks
143+
144+
- `linter all`
145+
- `cargo check --workspace --all-targets --all-features`
146+
- `cargo test --doc --workspace`
147+
- Pre-push hook (full gate)
148+
149+
### Manual Verification Scenarios
150+
151+
Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`.
152+
153+
| ID | Scenario | Command/Steps | Expected Result | Status | Evidence |
154+
| --- | -------------------------------------------------- | ------------------------------------------------ | ---------------------------------------- | ------ | -------- |
155+
| M1 | `rust-version` in Cargo.toml matches documentation | Compare `Cargo.toml`, `AGENTS.md`, SKILL.md | All three reference the same MSRV string | TODO | |
156+
| M2 | Workspace builds cleanly on the new MSRV toolchain | `rustup install <msrv>; cargo +<msrv> check ...` | Exit 0 with no errors | TODO | |
157+
158+
### Acceptance Verification
159+
160+
| AC ID | Status (`TODO`/`DONE`) | Evidence |
161+
| ----- | ---------------------- | -------- |
162+
| AC1 | TODO | |
163+
| AC2 | TODO | |
164+
| AC3 | TODO | |
165+
| AC4 | TODO | |
166+
| AC5 | TODO | |
167+
| AC6 | TODO | |
168+
| AC7 | TODO | |
169+
170+
## Risks and Trade-offs
171+
172+
- **Too high a MSRV before crate extraction**: if `bittorrent-*` crates are extracted
173+
carrying a high MSRV, downstream BitTorrent projects may be forced to upgrade their
174+
toolchain. Setting a modest floor now (e.g. current stable minus two releases) gives
175+
the extracted crates a clean, defensible starting point.
176+
- **Too low a MSRV after extraction**: the application layer has no reason to stay
177+
conservative; a low MSRV denies developers access to new stable APIs and better
178+
compiler diagnostics.
179+
- **Drift without a MSRV CI job**: a stated MSRV is only trustworthy if CI verifies it.
180+
If a conservative MSRV is chosen, a MSRV CI job should be added.
181+
182+
## References
183+
184+
- Related PRs: #1784
185+
- Related issue: #1786 (tighten lint config)
186+
- Blocked by: https://github.com/torrust/torrust-tracker/issues/1669 (package restructuring)

‎project-words.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Buildx
3939
byteorder
4040
callgrind
4141
CALLSITE
42+
callsites
4243
camino
4344
canonicalize
4445
canonicalized

0 commit comments

Comments
 (0)