From: Fabian Stelzer <fs@gigacodes.de>
Date: Wed, 01 Dec 2021 08:33:01 GMT
Subject: Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr
Message-ID: <20211201083301.ozrhi2brjk4zx5ll@fs>
In-Reply-To: <20211201053214.2902-1-sunshine@sunshineco.com>

On 01.12.2021 00:32, Eric Sunshine wrote:
>It has long been practice in this project for a command to emit its
>primary output to stdout so that it can be captured to a file or sent
>down a pipe, and to emit "chatty" messages (such as those reporting
>progress) to stderr so that they don't interfere with the primary
>output. However, this idiomatic Unix practice is not necessarily
>universally understood and may be at odds with other schools of thought,
>such as the somewhat common one that only error messages should go to
>stderr, and all other messages to stdout. Let's help newcomers by
>documenting how stdout and stderr are used on this project.
>
>Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
>---
> Documentation/CodingGuidelines | 26 ++++++++++++++++++++++++++
> 1 file changed, 26 insertions(+)
>
>diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
>index 711cb9171e..44dd178dc9 100644
>--- a/Documentation/CodingGuidelines
>+++ b/Documentation/CodingGuidelines
>@@ -499,6 +499,32 @@ For Python scripts:
>  - Where required libraries do not restrict us to Python 2, we try to
>    also be compatible with Python 3.1 and later.
>
>+
>+Program Output
>+
>+ We make a distinction between a command's primary output and output
>+ which is merely chatty feedback (for instance, status messages,
>+ running transcript, or progress display), as well as error messages.
>+ Roughly speaking, a command's primary output is that which one might
>+ want to capture to a file or send down a pipe; its chatty output
>+ should not interfere with those use-cases.
>+
>+ As such, primary output should be sent to the standard output stream
>+ (stdout), and chatty output should be sent to the standard error
>+ stream (stderr). Examples of commands which produce primary output
>+ include `git log`, `git show`, and `git branch --list` which generate
>+ output on the stdout stream.
>+
>+ Not all commands have primary output; this is often true of commands
>+ whose main function is to perform an action. Some action commands are
>+ silent, whereas others are chatty. An example of a chatty action
>+ commands is `git clone` with its "Cloning into '<path>'..." and
>+ "Checking connectivity..." status messages which it sends to the
>+ stderr stream.
>+
>+ Error messages are always sent to the stderr stream.
>+

This is not necessarily true in the context of the tests.
We just spoke about this in: 
https://lore.kernel.org/git/211130.86wnkpd6ou.gmgdl@evledraar.gmail.com/T/#u

I don't think it necessary to bloat this explanation with the test details.  
But mentioning it as an exception would be good.