Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ADR-7: CLI output presentation #55

Merged
merged 1 commit into from
Nov 14, 2024
Merged

Add ADR-7: CLI output presentation #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/ADR-7-CLI-Output-Presentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Status

📜 Proposed 2024-11-13

# Context

In order to allow easy composability of the command line interface (CLI) programs, the output data can be sent to standard output (*stdout*) or standard error (*stderr*) streams.
In Unix CLI tools, output conventions typically dictate that:

* **stdout** is used for regular output from a command. It typically includes the main results or data that the command is designed to produce. For example, the contents of a file when using `cat`, or the list of files in a directory when using `ls`.

* **stderr** is used for error messages and diagnostic information. Any warnings, errors, or debug information that is not part of the main output of the tool will usually be sent to stderr. For example, an error message indicating that a file does not exist when using `cat`.

These conventions help users and scripts to easily differentiate between normal output and error messages, enabling more effective error handling and output redirection.

This also aligns with [UNIX philisophy][bell-journal] (from *The Bell System Technical Journal*):
>Expect the output of every program to become the input to another, as yet unknown, program.
>Don't clutter output with extraneous information.
>Avoid stringently columnar or binary input formats.
>Don't insist on interactive input.

# Decision

`cardano-cli` should output its results to `stdout` and any diagnostic messages to `stderr`.

# Consequences

Some of `cardano-cli` commands are not following this principle.
This will require updating them to make things consistent across all the commands.

# References

1. [Unix Philosophy - Wikipedia][unix-philosophy]
1. [UNIX Time-Sharing System - The Bell System Technical Journal][bell-journal]

[unix-philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy
[bell-journal]: https://archive.org/details/bstj57-6-1899/mode/2up

1 change: 1 addition & 0 deletions docs/Architecture-Decision-Records.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
* ✅ [[ADR-2 Module structure for generators]]
* 📜 [[ADR-3 Dependencies version constraints in cabal file]]
* 📜 [[ADR-6 Using optparse-applicative main repository]]
* 📜 [[ADR-7 CLI Output Presentation]]

## Legend

Expand Down
Loading