docs(tracker-client): define CLI I/O contract and ADRs#1760
Merged
josecelano merged 2 commits intoMay 12, 2026
Conversation
There was a problem hiding this comment.
Pull request overview
Establishes a tracker-client–scoped documentation set defining the expected CLI I/O contract (stdout/stderr, JSON-first output, exit codes), adds an ADR capturing the rationale/migration policy, and adds issue specification docs for upcoming tracker-checker/client work.
Changes:
- Added Tracker CLI I/O contract documentation for JSON-first output, channel rules, and exit code semantics.
- Added tracker-client ADR folder with index and an ADR formalizing the contract + migration/testing strategy.
- Added issue specs for #1042, #1178, and #1564 aligned to the new contract and planned behavior.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/issues/open/1564-tracker-client-change-default-peer-id.md | New spec documenting planned PeerId prefix change and rollout plan. |
| docs/issues/open/1178-tracker-checker-udp-add-monitor-uptime-command.md | New spec for a UDP monitor command with NDJSON probe events + JSON summary. |
| docs/issues/open/1042-tracker-checker-http-improve-error-message-json-config.md | New spec for surfacing JSON parse errors and adopting structured stderr errors + exit code 2. |
| console/tracker-client/README.md | Links tracker-client README to the new contract and ADR docs; minor markdown cleanup. |
| console/tracker-client/docs/contracts/tracker-cli-io-contract.md | New contract defining output formats, channels, error envelope, and exit codes. |
| console/tracker-client/docs/adrs/README.md | New ADR README introducing tracker-client ADR scope and index. |
| console/tracker-client/docs/adrs/index.md | New ADR index table for tracker-client ADRs. |
| console/tracker-client/docs/adrs/20260512080000_define_tracker_cli_io_contract_and_error_handling.md | New ADR formalizing the CLI I/O contract and progressive migration approach. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1760 +/- ##
===========================================
- Coverage 79.46% 79.44% -0.03%
===========================================
Files 368 368
Lines 27302 27302
Branches 27302 27302
===========================================
- Hits 21695 21689 -6
- Misses 5323 5333 +10
+ Partials 284 280 -4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
… field name - Fix Azureus-style PeerId example in issue 1564 spec: add missing '-' separator after version field (b"-RC3000-000000000000" not b"-RC53070047639607806") - Align monitor probe event field name in contract example: use 'status' (matching issue 1178 spec) instead of 'result' - Use null for elapsed_ms on timeout events (matching 1178 spec convention) Addresses Copilot review suggestions on PR torrust#1760.
Member
Author
|
ACK a9b1064 |
josecelano
added a commit
to josecelano/torrust-tracker
that referenced
this pull request
May 12, 2026
The issue torrust#1743 implementation added paths-ignore rules to testing.yaml and os-compatibility.yaml but missed container.yaml and generate_coverage_pr.yaml. Docs-only pull requests (e.g. PR torrust#1760) were still triggering the container build and coverage jobs unnecessarily. Add the same paths-ignore exclusions to both workflows and update the docs-lint.yaml path-policy comment to accurately reflect which workflows carry the rule.
josecelano
added a commit
that referenced
this pull request
May 12, 2026
…erage workflows 2b177a2 fix(ci): add docs-only paths-ignore to container and coverage workflows (Jose Celano) Pull request description: ## Bug Issue #1743 added `paths-ignore` rules to the CI "docs-only fast path" for `testing.yaml` and `os-compatibility.yaml`, but two workflows were missed: - `container.yaml` — the container build job - `generate_coverage_pr.yaml` — the coverage report job As a result, docs-only pull requests (e.g. PR #1760) were still triggering the container build and coverage jobs unnecessarily, wasting CI minutes and delaying feedback. ## Fix Add the same `paths-ignore` exclusions to both workflows: ```yaml paths-ignore: - "**/*.md" - "project-words.txt" ``` Also update the path-policy comment in `docs-lint.yaml` to accurately list all workflows that carry the `paths-ignore` rule (replacing the stale list that mentioned `db-compatibility.yaml` and `db-benchmarking.yaml`, which are already scoped to code paths via `paths:` inclusion rules). ## Changed files - `.github/workflows/container.yaml` — Added `paths-ignore` to both `push` and `pull_request` triggers, plus path-policy comment. - `.github/workflows/generate_coverage_pr.yaml` — Added `paths-ignore` to the `pull_request` trigger, plus path-policy comment. - `.github/workflows/docs-lint.yaml` — Updated header comment to correctly list workflows that carry `paths-ignore` rules. ## References - Fixes part of issue #1743 - Related to PR #1760 (docs-only PR that triggered unnecessary CI jobs) ACKs for top commit: josecelano: ACK 2b177a2 Tree-SHA512: 3e262552149f3de49d25ce4afb2a664dd3e540b4b6ba10c2d18e25f608d517f6c6993f191d8fed006882241ef7cd9da1d62937a3d3e2588e2fa6659b3392353c
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
PeerIduse in clients #1564 with aligned acceptance criteria and references to the new contractValidation
Notes
This PR establishes the desired target-state contract for console/tracker-client and uses progressive migration for existing behavior that is not yet fully aligned.