Document OpenBMC message registry requirements

We get lots of patches to this file, and in general most tend to break
these implicit rules on their first patchset.  Lets try to document in
this file the expectations.

Signed-off-by: Ed Tanous <edtanous@google.com>
Change-Id: Icb988adb27a1a1fab77c30e7f6119eaef48aa60d

1 files changed, 41 insertions, 0 deletions

diff --git a/redfish-core/include/registries/openbmc_message_registry.hpp b/redfish-core/include/registries/openbmc_message_registry.hpp
index 80d30c30f6..4810eb479b 100644
--- a/redfish-core/include/registries/openbmc_message_registry.hpp
+++ b/redfish-core/include/registries/openbmc_message_registry.hpp
@@ -16,6 +16,47 @@
 #pragma once
 #include <registries.hpp>
 
+/*
+    Please read this before making edits to the structure below.
+
+    Messages in this registry are intended to be generally useful across
+   OpenBMC systems.  To that end, there are a number of guidelines needed for
+   messages in this file to remain useful across systems.
+
+    1. Messages should not be specific to a piece or type of hardware. Generally
+   this involves not using terms like "CPU", "Drive", "Backplane", etc in the
+   message strings, unless that behavior is specific to that particular piece of
+   hardware.
+   Incorrect: MemoryOverheated
+   Correct: DeviceOverheated
+   Correct: MemoryECCError (ECC is specific to memory, therefore class specific
+   is acceptable)
+
+    2. Messages should not use any proprietary, copyright, or company-specific
+   terms.  In general, messages should prefer the industry accepted term.
+
+    3. Message strings should be human readable, and read like a normal
+   sentence.  This generally involves placing the substitution parameters in the
+   appropriate place in the string.
+
+   Incorrect: "An error occurred.  Device: %1"
+
+   Correct: "An error occurred on device %1".
+
+    4. Message registry versioning semantics shall be obeyed.  Adding new
+   messages require an increment to the subminor revision.  Changes to existing
+   messages require an increment to the patch version.  If the copyright year is
+   different than the current date, increment it when the version is changed.
+
+   5. If you are changing this in your own downstream company-specific fork,
+   please change the "id" field below away from "OpenBMC.0.X.X" to something of
+   the form of "CompanyName.0.X.X".  This is to ensure that when a system is
+   found in industry that has modified this registry, it can be differentiated
+   from the OpenBMC project maintained registry.
+
+   6. Keep the below list alphabetized by message id.
+*/
+
 namespace redfish::registries::openbmc
 {
 const Header header = {