From d310d544821307aec386df5ff59d4e7db5d0d0c8 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Wed, 13 May 2026 11:14:44 +0100 Subject: [PATCH 1/3] docs(issues): add #1771 spec and spec-first PR workflow --- .../skills/dev/planning/create-issue/SKILL.md | 20 ++ ...clients-into-unified-tracker-client-cli.md | 275 ++++++++++++++++++ docs/issues/open/669-overhaul-clients.md | 8 +- docs/templates/ISSUE.md | 1 + 4 files changed, 301 insertions(+), 3 deletions(-) create mode 100644 docs/issues/open/1771-merge-clients-into-unified-tracker-client-cli.md diff --git a/.github/skills/dev/planning/create-issue/SKILL.md b/.github/skills/dev/planning/create-issue/SKILL.md index 35c3cbf5b..b53d2dae1 100644 --- a/.github/skills/dev/planning/create-issue/SKILL.md +++ b/.github/skills/dev/planning/create-issue/SKILL.md @@ -38,6 +38,15 @@ Lifecycle docs: 4. **Move spec file to `docs/issues/open/`** and include the issue number 5. **Pre-commit checks** and commit the spec +For complex or high-impact issues, a **spec-first PR** is recommended: + +- Open a branch containing only issue-spec/EPIC documentation changes +- Submit and merge that PR into `develop` first +- Start implementation only after the specification PR has been reviewed and merged + +This improves visibility and allows maintainers/contributors to review scope and acceptance +criteria before code changes begin. + **Never create the GitHub issue before the user reviews and approves the specification.** ## Step-by-Step Process @@ -114,6 +123,17 @@ git commit -S -m "docs(issues): add issue specification for #{number}" git push {your-fork-remote} {branch} ``` +### Optional Step 6 (Recommended for Complex Issues): Spec-Only PR + +When the issue is complex, cross-cutting, or likely to need scope negotiation, open a PR that +contains only the issue specification changes: + +1. Branch from `develop` +2. Commit only spec changes (`docs/issues/`, and if needed templates/skills) +3. Push branch and open PR targeting `develop` +4. Merge PR after review +5. Start implementation work in a separate branch/PR + ## Naming Convention File name format: `{number}-{short-description}.md` diff --git a/docs/issues/open/1771-merge-clients-into-unified-tracker-client-cli.md b/docs/issues/open/1771-merge-clients-into-unified-tracker-client-cli.md new file mode 100644 index 000000000..826f916ea --- /dev/null +++ b/docs/issues/open/1771-merge-clients-into-unified-tracker-client-cli.md @@ -0,0 +1,275 @@ +--- +doc-type: issue +issue-type: feature +status: planned +priority: p2 +github-issue: 1771 +spec-path: docs/issues/open/1771-merge-clients-into-unified-tracker-client-cli.md +branch: "1771-merge-clients-into-unified-tracker-client-cli" +related-pr: null +last-updated-utc: 2026-05-13 10:35 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - console/tracker-client/src/bin/http_tracker_client.rs + - console/tracker-client/src/bin/udp_tracker_client.rs + - console/tracker-client/src/bin/tracker_checker.rs + - packages/tracker-client/ + - console/tracker-client/ +--- + + + +# Issue #1771 — Merge all tracker client tools into a single unified `tracker_client` CLI + +## Goal + +Replace the three separate client binaries (`http_tracker_client`, `udp_tracker_client`, +`tracker_checker`) with a single `tracker_client` binary that supports all their use-cases +under a unified command-line interface. + +## Background + +Three binaries currently ship with the tracker to support testing and development workflows: + +- **`http_tracker_client`** — sends `announce` and `scrape` requests to HTTP trackers, returns + JSON. +- **`udp_tracker_client`** — sends `announce` and `scrape` requests to UDP trackers, returns + JSON. +- **`tracker_checker`** — checks whether UDP trackers, HTTP trackers, and health-check endpoints + are alive and responding correctly. + +The domain library code has already been extracted into the `packages/tracker-client` package +(see issue #1067). The remaining step is to unify the three binary entry points into a single +CLI and retire the old per-protocol binaries. + +The idea of merging these tools was first proposed in +[discussion #660](https://github.com/torrust/torrust-tracker/discussions/660) and tracked as +the final goal of EPIC [#669](https://github.com/torrust/torrust-tracker/issues/669). + +### Design decisions + +**CLI shape — Option B: explicit protocol subcommand.** The scope of this issue is a mechanical +port: the three independent binaries are moved into a single `tracker_client` binary with +explicit protocol subcommands. No behaviour changes are introduced beyond the unification itself. + +```sh +tracker_client http announce http://127.0.0.1:7070 9c38422213e30bff212b30c360d26f9a02136422 +tracker_client udp announce udp://127.0.0.1:6969 9c38422213e30bff212b30c360d26f9a02136422 +tracker_client check -- --config-path ./tracker_checker.json +``` + +An alternative CLI shape was proposed in discussion #660 by da2ce7: auto-detect the protocol +from the URL scheme (`udp://` → UDP, `http://`/`https://` → HTTP), reducing the required +subcommand depth: + +```sh +tracker_client announce udp://127.0.0.1:6969 9c38422213e30bff212b30c360d26f9a02136422 +tracker_client scrape http://127.0.0.1:7070 9c38422213e30bff212b30c360d26f9a02136422 +``` + +This idea is **out of scope here** — the goal of this issue is the simplest possible unification +(a direct port, not a redesign). The auto-detection approach will be reconsidered in a follow-up +issue once the single binary exists and all three use-cases are verified. + +Potential future additive UX (follow-up issue, not this one): + +```sh +tracker_client announce http://127.0.0.1:7070 9c38422213e30bff212b30c360d26f9a02136422 +tracker_client announce udp://127.0.0.1:6969 9c38422213e30bff212b30c360d26f9a02136422 +tracker_client check -- --config-path ./tracker_checker.json +``` + +In that model, top-level `announce` and `scrape` would behave as optional convenience commands +that dispatch internally to `http` or `udp` based on URL scheme. Explicit protocol subcommands +would remain supported. + +#### CLI shape options: pros and cons + +| | **Option A — URL-scheme auto-detection** | **Option B — Explicit protocol subcommand** | +| -------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| **Pros** | Shorter commands; matches how tracker URLs naturally appear in torrent files and tracker lists | Clear code separation per protocol; `--help` reveals all subcommands; error messages are unambiguous | +| | No need to remember whether to type `http` or `udp` before the action | Easier to extend with protocol-specific flags without polluting a shared namespace | +| | Feels more ergonomic for interactive use | Simple mechanical port — minimal risk for this issue | +| **Cons** | Requires URL parsing before dispatch; edge cases (e.g. custom ports, missing scheme) must be handled explicitly | More verbose at the command line; users must always specify the protocol even when the URL already carries that information | +| | Protocol-specific flags can collide in a flat namespace | Slightly redundant: the URL scheme and the subcommand both encode the protocol | + +**Output format — JSON default.** `--format=json` is the default output mode for all +subcommands; `--format=text` produces human-friendly output. The flag must be consistent across +all subcommands. + +**Legacy binary strategy — deprecate in-place for approximately one year.** The three old +binaries (`http_tracker_client`, `udp_tracker_client`, `tracker_checker`) are widely referenced +in the Torrust organization website, blog posts, and external documentation. To allow time for +those references to be updated, the old binaries will be kept as-is — no new features will be +added to them — and will print a deprecation warning on startup directing users to +`tracker_client`. They will be removed no earlier than approximately one year after `tracker_client` +is released and documented. The removal milestone should be tracked in a follow-up issue. + +**Checker subcommand name — `check`.** Consistent with the verb pattern used by `announce` and +`scrape`, and moves from the old binary noun (`tracker_checker`) to an imperative verb (`check`). + +**REST API client:** extending the CLI with a `tracker_client api` subcommand to interact +with the Torrust Tracker management REST API was mentioned in discussion #660. This is out of scope +for this issue but should be kept in mind for the CLI shape. + +## Scope + +### In Scope + +- Define the final CLI interface (command/subcommand hierarchy, argument names, defaults). +- Implement a single `tracker_client` binary entry point in `console/tracker-client/src/bin/`. +- Wire all three existing use-cases (HTTP announce/scrape, UDP announce/scrape, checker) into + the new CLI. +- Unified `--format=` flag shared across all subcommands, with JSON as the default. +- Add deprecation notices to the three legacy binaries (print warning on startup, no new + features). Track removal (≥ 1 year after release) in a follow-up issue. +- Update in-repo docs and skills that reference the old binary names. + +### Out of Scope + +- Implementation of missing announce parameters (#1532, #1533) — those are tracked separately. +- REST API console client — deferred to a future issue. +- Top-level `announce`/`scrape` convenience commands that auto-dispatch by URL scheme + (future additive UX). +- Changes to the `packages/tracker-client` library itself (only the CLI entrypoint is in scope + unless structural changes are required for the CLI unification). + +## Implementation Plan + +Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. + +| ID | Status | Task | Notes / Expected Output | +| --- | ------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| T1 | TODO | Implement unified `tracker_client` entry point | New `console/tracker-client/src/bin/tracker_client.rs` with `http`, `udp`, and `check` subcommands. | +| T2 | TODO | Add unified `--format=` flag | JSON default; flag works identically across all subcommands. | +| T3 | TODO | Add deprecation notices to legacy binaries | Each old binary prints a deprecation warning on startup; no new features added to them. | +| T4 | TODO | Update in-repo docs, skills, and CI references | All in-repo references to old binary names updated or annotated. | +| T5 | TODO | Validate gates and regression | `linter all` and relevant tests pass; existing tests ported or replaced. | +| T6 | TODO | Run manual verification scenarios | Execute the local-tracker manual test matrix and record status/evidence for every scenario. | + +## Manual Verification Plan (Local Tracker) + +The refactor must be manually validated against a locally running tracker to ensure no behavior +regression across protocol commands. + +### Test Setup + +Terminal A (start local tracker): + +```sh +mkdir -p ./storage/tracker/etc/ +cp ./share/default/config/tracker.development.sqlite3.toml ./storage/tracker/etc/tracker.toml +TORRUST_TRACKER_CONFIG_TOML_PATH="./storage/tracker/etc/tracker.toml" cargo run +``` + +Terminal B (run client scenarios against local tracker): + +Use this sample info hash in all announce/scrape tests: + +```text +9c38422213e30bff212b30c360d26f9a02136422 +``` + +### Scenario Matrix and Progress Tracking + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command | Expected Result | Status | Evidence | +| --- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | --------------------------- | +| M1 | HTTP announce (JSON default) | `cargo run --bin tracker_client http announce http://127.0.0.1:7070 9c38422213e30bff212b30c360d26f9a02136422` | Command exits 0 and prints valid JSON announce response | TODO | {command output / log path} | +| M2 | HTTP scrape (JSON default) | `cargo run --bin tracker_client http scrape http://127.0.0.1:7070 9c38422213e30bff212b30c360d26f9a02136422` | Command exits 0 and prints valid JSON scrape response | TODO | {command output / log path} | +| M3 | UDP announce (JSON default) | `cargo run --bin tracker_client udp announce udp://127.0.0.1:6969 9c38422213e30bff212b30c360d26f9a02136422` | Command exits 0 and prints valid JSON announce response | TODO | {command output / log path} | +| M4 | UDP scrape (JSON default) | `cargo run --bin tracker_client udp scrape udp://127.0.0.1:6969 9c38422213e30bff212b30c360d26f9a02136422` | Command exits 0 and prints valid JSON scrape response | TODO | {command output / log path} | +| M5 | Checker command | `TORRUST_CHECKER_CONFIG='{"udp_trackers":["127.0.0.1:6969"],"http_trackers":["http://127.0.0.1:7070"],"health_checks":["http://127.0.0.1:1212/api/health_check"]}' cargo run --bin tracker_client check` | Command exits 0 and reports successful UDP/HTTP/health checks in JSON | TODO | {command output / log path} | +| M6 | HTTP announce (text format) | `cargo run --bin tracker_client http announce --format=text http://127.0.0.1:7070 9c38422213e30bff212b30c360d26f9a02136422` | Command exits 0 and prints human-readable response | TODO | {command output / log path} | +| M7 | UDP scrape (text format) | `cargo run --bin tracker_client udp scrape --format=text udp://127.0.0.1:6969 9c38422213e30bff212b30c360d26f9a02136422` | Command exits 0 and prints human-readable response | TODO | {command output / log path} | + +Notes: + +- Update the `Status` and `Evidence` columns as each scenario is executed. +- If any scenario fails, capture the failing output and add a short diagnosis entry in the + progress log before continuing. + +## Progress Tracking + +### Workflow Checkpoints + +- [x] Spec drafted in `docs/issues/drafts/` +- [x] Spec reviewed and approved by user/maintainer +- [x] GitHub issue created and issue number added to this spec +- [ ] Implementation completed +- [ ] Reviewer validated acceptance criteria and updated checkboxes +- [ ] Committer verified spec progress is up to date before commit +- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/` + +### Progress Log + +- 2026-05-13 00:00 UTC - Copilot - Created draft spec from discussion #660 and EPIC #669. +- 2026-05-13 10:00 UTC - Copilot - Recorded design decisions: Option B CLI shape, JSON default output, ~1-year deprecation window for legacy binaries, `check` subcommand name. +- 2026-05-13 10:10 UTC - Copilot - Added future additive UX note for top-level `announce`/`scrape` aliases that auto-dispatch by URL scheme; kept out of scope for this issue. +- 2026-05-13 10:20 UTC - Copilot - Added explicit acceptance criterion to prevent scope drift: top-level `announce`/`scrape` auto-dispatch aliases are not part of this issue. +- 2026-05-13 10:30 UTC - Copilot - Added local-tracker manual verification plan with concrete commands and a scenario status matrix. +- 2026-05-13 10:35 UTC - Copilot - Opened GitHub issue #1771 and moved spec from drafts to open. + +## Acceptance Criteria + +- [ ] AC1: A single `tracker_client` binary exists with `http announce`, `http scrape`, + `udp announce`, `udp scrape`, and `check` subcommands, all behaving equivalently to the + current per-protocol binaries. +- [ ] AC2: `--format=json` (default) produces valid JSON on stdout for all subcommands. +- [ ] AC3: `--format=text` produces human-readable output for all subcommands. +- [ ] AC4: Each legacy binary (`http_tracker_client`, `udp_tracker_client`, `tracker_checker`) + prints a deprecation notice on startup directing users to `tracker_client`; their existing + behaviour is otherwise unchanged. +- [ ] AC5: A follow-up issue for removing the legacy binaries (no earlier than ~1 year after + `tracker_client` ships) is linked from this spec or the EPIC. +- [ ] AC6: In-repo docs and skill files that reference old binary names are updated. +- [ ] AC7: Top-level `announce`/`scrape` auto-dispatch aliases are not implemented in this + issue (kept for follow-up to prevent scope drift). +- [ ] AC8: `linter all` exits with code `0`. +- [ ] AC9: Relevant tests pass. +- [ ] AC10: Manual verification matrix scenarios (M1-M7) are executed against a local tracker, + with status and evidence recorded for each. + +### Acceptance Verification + +| AC ID | Status (`TODO`/`DONE`) | Evidence | +| ----- | ---------------------- | ------------------------------------------------------------------- | +| AC1 | TODO | {test/log/PR link} | +| AC2 | TODO | {test/log/PR link} | +| AC3 | TODO | {test/log/PR link} | +| AC4 | TODO | {test/log/PR link} | +| AC5 | TODO | {follow-up issue link} | +| AC6 | TODO | {test/log/PR link} | +| AC7 | TODO | {CLI help/output showing only explicit protocol path in this issue} | +| AC8 | TODO | {test/log/PR link} | +| AC9 | TODO | {test/log/PR link} | +| AC10 | TODO | {manual verification matrix with statuses and evidence completed} | + +## Risks and Trade-offs + +- **External documentation references**: the old binary names appear in the Torrust website, + blog posts, and other organization-wide materials that cannot be updated in a single PR. + Mitigation: keep the legacy binaries alive for approximately one year after `tracker_client` + ships; add startup deprecation warnings; track removal in a dedicated follow-up issue. +- **Inconsistency across subcommands**: if output format handling is not centralized, each + subcommand may behave differently. + Mitigation: implement a shared output formatter before wiring subcommands. +- **Scope creep**: the Tracker Checker has a richer config-file-driven interface; merging + it may introduce complexity into the shared CLI argument parser. + Mitigation: keep the checker as a self-contained subcommand; do not restructure its + internals in this issue. + +## References + +- Parent EPIC: +- GitHub issue: +- Spec: [docs/issues/open/669-overhaul-clients.md](../open/669-overhaul-clients.md) +- Original discussion: +- HTTP Tracker Client source: `console/tracker-client/src/console/clients/http/` +- UDP Tracker Client source: `console/tracker-client/src/console/clients/udp/` +- Tracker Checker source: `console/tracker-client/src/console/clients/checker/` +- `tracker-client` package: `packages/tracker-client/` +- Related: #1532, #1533, #1561, #1562, #1563, #1564 diff --git a/docs/issues/open/669-overhaul-clients.md b/docs/issues/open/669-overhaul-clients.md index 9352702f4..d6cb8d71c 100644 --- a/docs/issues/open/669-overhaul-clients.md +++ b/docs/issues/open/669-overhaul-clients.md @@ -59,9 +59,10 @@ This EPIC systematically improves each tool and eventually unifies them. ### Unified Tracker Client -| Issue | Title | Status | -| --------------------------------------------------------------- | ------------------------------------------- | ------ | -| [#1564](https://github.com/torrust/torrust-tracker/issues/1564) | Change the default `PeerId` used in clients | Open | +| Issue | Title | Status | +| --------------------------------------------------------------- | ------------------------------------------------------------------- | ------ | +| [#1564](https://github.com/torrust/torrust-tracker/issues/1564) | Change the default `PeerId` used in clients | Open | +| [#1771](https://github.com/torrust/torrust-tracker/issues/1771) | Merge clients into a unified `tracker_client` CLI (mechanical port) | Open | ## Already Closed Sub-Issues @@ -104,6 +105,7 @@ Each pending sub-issue has a dedicated spec document in this folder: - [1561-http-tracker-client-avoid-duplicating-announce-suffix.md](1561-http-tracker-client-avoid-duplicating-announce-suffix.md) - [1562-http-tracker-client-add-option-show-response-pretty-json.md](1562-http-tracker-client-add-option-show-response-pretty-json.md) - [1563-udp-tracker-client-add-option-show-response-pretty-json.md](1563-udp-tracker-client-add-option-show-response-pretty-json.md) +- [1771-merge-clients-into-unified-tracker-client-cli.md](1771-merge-clients-into-unified-tracker-client-cli.md) ## References diff --git a/docs/templates/ISSUE.md b/docs/templates/ISSUE.md index 1dbd48e59..51748086a 100644 --- a/docs/templates/ISSUE.md +++ b/docs/templates/ISSUE.md @@ -55,6 +55,7 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. - [ ] Spec drafted in `docs/issues/drafts/` - [ ] Spec reviewed and approved by user/maintainer - [ ] GitHub issue created and issue number added to this spec +- [ ] (Optional, recommended for complex issues) Spec-only PR merged into `develop` before implementation - [ ] Implementation completed - [ ] Reviewer validated acceptance criteria and updated checkboxes - [ ] Committer verified spec progress is up to date before commit From 224b4e950b0b4bee6a7c3a4b3eec809f01cc4145 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Wed, 13 May 2026 11:20:47 +0100 Subject: [PATCH 2/3] docs(templates): require manual verification in issue workflows --- .../skills/dev/planning/create-issue/SKILL.md | 19 ++++++++++++ docs/templates/EPIC.md | 12 ++++++++ docs/templates/ISSUE.md | 29 +++++++++++++++++++ 3 files changed, 60 insertions(+) diff --git a/.github/skills/dev/planning/create-issue/SKILL.md b/.github/skills/dev/planning/create-issue/SKILL.md index b53d2dae1..3ddbbc993 100644 --- a/.github/skills/dev/planning/create-issue/SKILL.md +++ b/.github/skills/dev/planning/create-issue/SKILL.md @@ -72,6 +72,12 @@ explicitly during implementation: - `Progress Tracking` (`Workflow Checkpoints` and first `Progress Log` entry) - `Acceptance Criteria` and `Acceptance Verification` +The draft must also include a verification policy that is explicit and enforceable: + +- Automatic checks to run after implementation (`linter all`, relevant tests, pre-push checks when applicable) +- Manual verification scenarios with status + evidence tracking (mandatory) +- A post-implementation acceptance criteria review step + Use **placeholders** for the issue number until after creation (for example `github-issue: null` or `[To be assigned]` in the heading/body content). @@ -134,6 +140,19 @@ contains only the issue specification changes: 4. Merge PR after review 5. Start implementation work in a separate branch/PR +## Verification Requirements for Issue Specs + +When creating or updating issue/epic specs, ensure these requirements are present in the spec +before implementation starts: + +1. **Automatic verification**: list required automated checks. +2. **Manual verification**: define concrete manual scenarios with commands/steps and expected results. +3. **Evidence tracking**: include status/evidence fields for manual scenarios. +4. **Post-implementation AC review**: explicitly require acceptance criteria to be re-reviewed + against observed behavior before closing the issue. + +Do not treat an issue as complete only because automated tests pass; manual validation is required. + ## Naming Convention File name format: `{number}-{short-description}.md` diff --git a/docs/templates/EPIC.md b/docs/templates/EPIC.md index 808dc6ec8..b2bd679a9 100644 --- a/docs/templates/EPIC.md +++ b/docs/templates/EPIC.md @@ -49,6 +49,12 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. Describe rollout phases, dependency order, and merge strategy. +For each subissue implementation in this EPIC, the default completion policy is: + +1. Run automatic checks (`linter all`, relevant tests, pre-push checks when applicable). +2. Run manual verification scenarios and record evidence. +3. Re-review acceptance criteria after implementation and update verification evidence. + ### Phase 1 - Outcome @@ -68,6 +74,9 @@ Describe rollout phases, dependency order, and merge strategy. - [ ] GitHub epic issue created and issue number added to this spec - [ ] Subissues created and linked in this spec - [ ] Subissue statuses kept up to date in the `Subissues` table +- [ ] For each implemented subissue: automatic checks completed and recorded +- [ ] For each implemented subissue: manual verification completed and recorded +- [ ] For each implemented subissue: acceptance criteria reviewed post-implementation - [ ] Epic acceptance criteria reviewed and checked off - [ ] Epic issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/` @@ -83,6 +92,9 @@ Append one line per meaningful update. - [ ] Implementation order is explicit and justified. - [ ] Dependencies and blockers are documented and current. - [ ] Epic status reflects actual state of linked subissues. +- [ ] Every completed subissue includes automated verification evidence. +- [ ] Every completed subissue includes manual verification evidence. +- [ ] Every completed subissue includes post-implementation acceptance criteria review. - [ ] Documentation and governance updates are included when required. ### Acceptance Verification diff --git a/docs/templates/ISSUE.md b/docs/templates/ISSUE.md index 51748086a..691f6f1a1 100644 --- a/docs/templates/ISSUE.md +++ b/docs/templates/ISSUE.md @@ -57,6 +57,9 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. - [ ] GitHub issue created and issue number added to this spec - [ ] (Optional, recommended for complex issues) Spec-only PR merged into `develop` before implementation - [ ] Implementation completed +- [ ] Automatic verification completed (`linter all`, relevant tests, and any pre-push checks) +- [ ] Manual verification scenarios executed and recorded (status + evidence) +- [ ] Acceptance criteria reviewed after implementation and updated with evidence - [ ] Reviewer validated acceptance criteria and updated checkboxes - [ ] Committer verified spec progress is up to date before commit - [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/` @@ -73,8 +76,34 @@ Append one line per meaningful update. - [ ] AC2: {Behavior/outcome that must be true} - [ ] `linter all` exits with code `0` - [ ] Relevant tests pass +- [ ] Manual verification scenarios are executed and documented (status + evidence) +- [ ] Acceptance criteria are re-reviewed after implementation and reflect actual behavior - [ ] Documentation is updated when behavior/workflow changes +## Verification Plan + +Define verification before implementation starts and execute it before closing the issue. + +### Automatic Checks + +- `linter all` +- Relevant tests for changed components +- Pre-push checks (when applicable) + +### Manual Verification Scenarios + +Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`. + +| ID | Scenario | Command/Steps | Expected Result | Status | Evidence | +| --- | ----------------- | ------------------------------------ | ------------------- | ------ | ---------------------------- | +| M1 | {Manual scenario} | {Exact command or interaction steps} | {Expected behavior} | TODO | {log/output/screenshot/path} | +| M2 | {Manual scenario} | {Exact command or interaction steps} | {Expected behavior} | TODO | {log/output/screenshot/path} | + +Notes: + +- Manual verification is mandatory even when automated tests pass. +- If a scenario fails, record the failure and diagnosis in the progress log before proceeding. + ### Acceptance Verification | AC ID | Status (`TODO`/`DONE`) | Evidence | From 56e0b1ac2784096c063bc6f684af486be7bf1e3a Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Wed, 13 May 2026 11:27:52 +0100 Subject: [PATCH 3/3] docs(skills): clarify spec PRs must target upstream repo --- .../skills/dev/planning/create-issue/SKILL.md | 21 ++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/.github/skills/dev/planning/create-issue/SKILL.md b/.github/skills/dev/planning/create-issue/SKILL.md index 3ddbbc993..2d6b4e483 100644 --- a/.github/skills/dev/planning/create-issue/SKILL.md +++ b/.github/skills/dev/planning/create-issue/SKILL.md @@ -136,9 +136,24 @@ contains only the issue specification changes: 1. Branch from `develop` 2. Commit only spec changes (`docs/issues/`, and if needed templates/skills) -3. Push branch and open PR targeting `develop` -4. Merge PR after review -5. Start implementation work in a separate branch/PR +3. Push branch to your fork remote (for example `josecelano`) +4. Open PR in the **upstream repository** (`torrust/torrust-tracker`) targeting `develop` +5. If using fork-based workflow, set head as `{fork-owner}:{branch}` (for example + `josecelano:1771-spec-first-pr-workflow`) +6. Do not open the PR in the fork repository unless explicitly requested +7. Merge PR after review +8. Start implementation work in a separate branch/PR + +Recommended GitHub CLI command for fork-based PRs: + +```bash +gh pr create \ + --repo torrust/torrust-tracker \ + --base develop \ + --head {fork-owner}:{branch} \ + --title "{title}" \ + --body-file {body-file} +``` ## Verification Requirements for Issue Specs