README: Begin documenting development style rules

The first rule enforces the use of stdout/stderr for logging. Rationale
is provided in the README.

Change-Id: Ibb5b62ea1341aa951fd42b15e9cd14a836842032
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>

1 files changed, 49 insertions, 1 deletions

diff --git a/README.md b/README.md
index 4293bbd..ce9881e 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,8 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
-## MBOX
+MBOX
+====
 
 This repo contains the protocol definition for the host to BMC mailbox
 communication specification which can be found in
@@ -23,3 +24,50 @@ of which can be found in Documentation/mboxd.md.
 
 Finally there is also an implementation of a mailbox daemon control program, the
 details of which can be found in Documentation/mboxctl.md.
+
+Style Guide
+===========
+
+Preamble
+--------
+
+This codebase is a mix of C (due to its heritage) and C++. This is an ugly
+split: message logging and error handling can be vastly different inside the
+same codebase. The aim is to remove the split one way or the other over time
+and have consistent approaches to solving problems.
+
+phosphor-mboxd is developed as part of the OpenBMC project, which also leads to
+integration of frameworks such as
+[phosphor-logging](https://github.com/openbmc/phosphor-logging). Specifically
+on phosphor-logging, it's noted that without care we can achieve absurd
+duplication or irritating splits in where errors are reported, as the C code is
+not capable of making use of the interfaces provided.
+
+Rules
+-----
+
+1. Message logging MUST be done to stdout or stderr, and MUST NOT be done
+   directly via journal APIs or wrappers of the journal APIs.
+
+   Rationale:
+
+   We have two scenarios where we care about output, with the important
+   restriction that the method must be consistent between C and C++:
+
+   1. Running in-context on an OpenBMC-based system
+   2. Running the test suite
+
+   In the first case it is desirable that the messages appear in the system
+   journal. To this end, systemd will by default capture stdout and stderr of
+   the launched binary and redirect it to the journal.
+
+   In the second case it is *desirable* that messages be captured by the test
+   runner (`make check`) for test failure analysis, and it is *undesirable* for
+   messages to appear in the system journal (as these are tests, not issues
+   affecting the health of the system they are being executed on).
+
+   Therefore direct calls to the journal MUST be avoided for the purpose of
+   message logging.
+
+   Note: This section specifically targets the use of phosphor-logging's
+   `log<T>()`. It does not prevent the use of `elog<T>()`.