docs(cli): define global CLI output contract ADR (#1798)#1800
Merged
josecelano merged 7 commits intoMay 20, 2026
Conversation
There was a problem hiding this comment.
Pull request overview
Establishes a repository-wide ADR that defines a single, canonical JSON-only CLI output contract (stdout result object + stderr NDJSON diagnostics, exit codes 0/1/2, and mandatory TTY refusal for stdout-result-data commands) for all first-party binaries in torrust-tracker, superseding the tracker-client–local ADR and adding follow-up migration planning.
Changes:
- Adds new ADR documenting the global CLI output contract and migration policy.
- Updates ADR index and tracker-client local ADR to reflect the new lifecycle/supersession policy.
- Adds/updates issue-spec docs (open issue spec + draft migration plan) and supporting skill/spellcheck entries.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
docs/adrs/20260519000000_define_global_cli_output_contract.md |
New ADR defining the global JSON-only CLI output contract, including TTY refusal and migration policy. |
docs/adrs/index.md |
Adds ADR index row and documents ADR lifecycle/status conventions. |
console/tracker-client/docs/adrs/20260512080000_define_tracker_cli_io_contract_and_error_handling.md |
Marks the tracker-client ADR as superseded by the new global ADR. |
docs/issues/open/1798-global-cli-output-contract-adr.md |
Adds/updates the #1798 issue spec with background, decisions, classification table, and progress tracking. |
docs/issues/drafts/cli-output-contract-migration.md |
Draft follow-up migration issue to bring existing binaries into compliance and enable clippy print lints. |
.github/skills/dev/planning/create-adr/SKILL.md |
Documents ADR - Status: header guidance (only for terminal states like Superseded). |
project-words.txt |
Adds eprint to the spellcheck allowlist. |
Comments suppressed due to low confidence (1)
docs/issues/open/1798-global-cli-output-contract-adr.md:46
- This section says the tracker-client local ADR has status "Accepted", but this PR updates that ADR to "Superseded". To avoid internal doc inconsistency, update this wording (e.g. “was previously Accepted” or reflect the new Superseded status).
The tracker already has a local CLI I/O contract, but it is scoped only to
`console/tracker-client`:
- `console/tracker-client/docs/adrs/20260512080000_define_tracker_cli_io_contract_and_error_handling.md`
(status: Accepted) — defines JSON default, stdout/stderr channel split, exit codes 0/1/2, and
NDJSON progress for monitor-style commands.
- `console/tracker-client/docs/contracts/tracker-cli-io-contract.md` — the normative companion
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --- | ||
| doc-type: issue | ||
| issue-type: task | ||
| status: open |
Comment on lines
+84
to
+87
| { | ||
| "kind": "tty_refusal", | ||
| "message": "stdout is a TTY; pipe the output to consume result data" | ||
| } |
josecelano
added a commit
to josecelano/torrust-tracker
that referenced
this pull request
May 20, 2026
…t#1798) - Fix issue spec frontmatter: status open → planned (matches repo convention for open issue specs). - Fix issue spec background: local ADR reference updated from "status: Accepted" to "superseded by ADR 20260519000000". - Fix ADR TTY-refusal example: add note that examples are pretty-printed; actual wire format is single-line NDJSON.
josecelano
added a commit
to josecelano/torrust-tracker
that referenced
this pull request
May 20, 2026
…t#1798) - Fix issue spec frontmatter: status open → planned (matches repo convention for open issue specs). - Fix issue spec background: local ADR reference updated from "status: Accepted" to "superseded by ADR 20260519000000". - Fix ADR TTY-refusal example: add note that examples are pretty-printed; actual wire format is single-line NDJSON.
josecelano
force-pushed
the
1798-global-cli-output-contract-adr
branch
from
89763c7 to
1dd8024
Compare
- Add docs/adrs/20260519000000_define_global_cli_output_contract.md with the full global CLI output contract (10 sections: channels, exit codes, binary classification, TTY refusal, verbosity, shared infra, redaction, lint guards, AI agent capture, migration policy). - Add ADR row to docs/adrs/index.md. - Mark tracker-client local ADR as superseded by the global ADR. - Update issue spec: T1–T6 and T9 DONE; binary classification table added; T3/T4 decisions recorded. - Add `eprint` to project-words.txt.
Merged ADRs are implicitly accepted via PR review. No `- Status:` header is needed for the common case. - Remove `- Status: Proposed` from the global CLI output contract ADR. - Add an ADR Lifecycle section to docs/adrs/index.md explaining the policy (status header only for special states: Superseded, etc.). - Add an ADR Status subsection to the create-adr skill with the same guidance.
…tion (torrust#1798) Draft issue spec covering: - Remove three deprecated binaries (udp_tracker_client, http_tracker_client, tracker_checker). - Migrate http_health_check to JSON stdout/stderr. - Wire TTY refusal into tracker_client. - Rewrite tracker-client console abstraction layer. - Replace library-level println! with tracing in packages/configuration and packages/udp-tracker-core. - Enable clippy::print_stdout / clippy::print_stderr as workspace-level deny lints once migration is complete.
…ecycle (torrust#1798) - Mark T7 DONE: workspace lint guard deferred to follow-up draft issue docs/issues/drafts/cli-output-contract-migration.md. - Reword T8 note: peer review via PR; merged to develop = accepted. - Update checkpoint: "ADR peer-reviewed and status set to Accepted" → "PR opened, reviewed, and merged to develop". - Fix close-checkpoint path: drafts/ → open/. - Reword AC10 to match the new ADR lifecycle (no explicit status field). - Reformat migration draft tables (column alignment only).
…t#1798) - Fix issue spec frontmatter: status open → planned (matches repo convention for open issue specs). - Fix issue spec background: local ADR reference updated from "status: Accepted" to "superseded by ADR 20260519000000". - Fix ADR TTY-refusal example: add note that examples are pretty-printed; actual wire format is single-line NDJSON.
Use `ndjson` as the code fence language instead of `json` to prevent the IDE's automatic JSON formatter from reformatting the single-line example into a multi-line block on save.
josecelano
force-pushed
the
1798-global-cli-output-contract-adr
branch
from
1dd8024 to
d8fb7f2
Compare
Member
Author
|
ACK d8fb7f2 |
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.
Closes #1798
Summary
Establishes a repository-wide Architectural Decision Record (ADR) that defines a single, canonical CLI output contract for every first-party binary in
torrust-tracker, aligned with the approach already adopted bytorrust-index(ADR-T-010).Changes
docs/adrs/20260519000000_define_global_cli_output_contract.md— new ADR with 10 sections:profilingout of scope)stdout-result-datacommands; exit 2 + JSON stderr diagnosticcli-commonfrom Torrust Index as referenceclippy::print_stdout/clippy::print_stderrdeny once migration complete (interacts with chore: migrate lint configuration to[workspace.lints]in Cargo.toml #1786).tmp/<cmd>.stdout/.tmp/<cmd>.stderrdocs/adrs/index.md— new ADR row +## ADR Lifecyclesection (merged = accepted;- Status:only for special terminal states like Superseded)console/tracker-client/docs/adrs/20260512080000_define_tracker_cli_io_contract_and_error_handling.md— status changed toSuperseded by 20260519000000docs/issues/open/1798-global-cli-output-contract-adr.md— spec updated (T1–T7, T9 DONE); binary classification table; T3/T4 decisions recorded; progress log updateddocs/issues/drafts/cli-output-contract-migration.md— new draft follow-up issue for migrating existing non-compliant binaries (46print!/println!/eprint!/eprintln!occurrences surveyed; 9-task migration plan).github/skills/dev/planning/create-adr/SKILL.md— added### ADR Statussubsection: do not add- Status:by default; only for Superseded / Deprecated statesproject-words.txt— addedeprintADR Lifecycle Note
An ADR present in
developormainis accepted — the PR review process is the acceptance gate. No explicit- Status: Acceptedheader is needed. This PR itself constitutes the acceptance review for ADR20260519000000.What is NOT in scope
The current codebase does not yet fully comply with the contract. Migration of existing non-compliant binaries is tracked in the draft follow-up issue
docs/issues/drafts/cli-output-contract-migration.mdand will be handled in a separate issue/PR.