feat(output)!: put the product on stdout and the narration on stderr - #122
Open
Ilyes512 wants to merge 2 commits into
Open
feat(output)!: put the product on stdout and the narration on stderr#122Ilyes512 wants to merge 2 commits into
Ilyes512 wants to merge 2 commits into
Conversation
Info wrote to stdout in both writers while Warn/Error/WriteErr already went to
stderr, so narration landed in the data stream: `specs template list -o json`
emitted an info object between the records, and `specs version -o json` answered
with an English sentence rather than a field.
Info now writes to stderr, and a WriteResult(record, format, args...) method
carries the single-line product a command answers with — pretty renders the
sentence, JSON marshals the record, so every stdout line stays a typed object.
Re-classified the call sites that are answers rather than narration:
- `version` reports {"version": "..."}; $(specs version) is unchanged.
- `template validate` reports {"valid": true|false} on both paths.
- `template list` writes an empty table when nothing is registered, so the empty
answer has the shape of the non-empty one, and narrates the hint on stderr.
- `template update` answers with a Name/Status/Latest table instead of
sentences, sharing the error-kind labels with `template list`.
Every other Info call site is narration and simply follows Info to stderr.
Refs #113
overview.md documented the old behaviour (`Info` → stdout) in three table rows, which is too little room for a rule the whole command tree has to follow. The contract, the Writer interface, the colour decision and the golden-file tests move to docs/content/docs/architecture/output.md, including guidance on which method a new call site needs; overview.md keeps a summary and a pointer. Also documents the split for users: how to script against stdout in README.md and the commands pages, and what `template update` now answers with. Refs #113
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
1 participant
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
Infomoves to stderr in both writers; a newWriter.WriteResult(record, format, args...)carries the single-line product on stdout (pretty renders the sentence, JSON marshals the record).version→{"version":"…"},template validate→{"valid":true|false}on both paths,template listwrites an empty table ([]) when nothing is registered,template updateanswers with aName/Status/Latesttable instead of sentences.Infocall site is narration and followsInfoto stderr;fmt.Fprintadded to the errcheck exclusions.executeCmdStreamsininternal/cmdfor stream-level assertions.docs/content/docs/architecture/output.md, which replaces theInfo → stdoutrows inoverview.md; README and the commands pages document how to script against stdout.Note:
template updatewith nothing checkable now prints an empty table plus a hint on stderr, where it previously printed nothing.Closes #113