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>
diff --git a/README.md b/README.md
index 4293bbd..ce9881e 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,8 @@
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 @@
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>()`.