From c4a28689dfd33cbc870f55dc4aae520c1ec57cd9 Mon Sep 17 00:00:00 2001
From: Mateusz Galazyn <228866+carbolymer@users.noreply.github.com>
Date: Thu, 14 Nov 2024 22:34:29 +0100
Subject: [PATCH] Add ADR-7: CLI output presentation (#55)

---
 docs/ADR-7-CLI-Output-Presentation.md | 38 +++++++++++++++++++++++++++
 docs/Architecture-Decision-Records.md |  1 +
 2 files changed, 39 insertions(+)
 create mode 100644 docs/ADR-7-CLI-Output-Presentation.md

diff --git a/docs/ADR-7-CLI-Output-Presentation.md b/docs/ADR-7-CLI-Output-Presentation.md
new file mode 100644
index 0000000..f6dfc47
--- /dev/null
+++ b/docs/ADR-7-CLI-Output-Presentation.md
@@ -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
+
diff --git a/docs/Architecture-Decision-Records.md b/docs/Architecture-Decision-Records.md
index de9229c..6a3ab1c 100644
--- a/docs/Architecture-Decision-Records.md
+++ b/docs/Architecture-Decision-Records.md
@@ -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