Document Redfish OEM resource policy

We've had some unwritten guidelines around OEM resources in the past.
This commit aims to document them in a way that we can be fair to all
contributors, and make clear the guidelines surrounding OEM schemas.

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

2 files changed, 74 insertions, 8 deletions

diff --git a/DEVELOPING.md b/DEVELOPING.md
index 3c33c6474d..11e7c93b31 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -117,14 +117,8 @@
    bmcweb's Redfish implementation, including Redfish OEM Resources, shall
    conform to the Redfish specification. Please keep bmcweb's [Redfish support
    document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md) updated.
-   Before adding a Redfish OEM schema or property first engage the DMTF's
-   Redfish working group to see if they are interested in adding the new
-   feature. The [Redfish Specification Forum](https://redfishforum.com/) is a
-   public Redfish forum to ask questions and request features. Redfish
-   "Supporter" and "Promoter" companies, which many companies working on OpenBMC
-   are, can request features via the Redfish code repository or via Redfish
-   meetings. For more information on Redfish and supported schemas visit
-   [Redfish.md](https://github.com/openbmc/bmcweb/blob/master/Redfish.md).
+   OEM schemas should conform and be developed in line with the rules in
+   [OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md).
 
 13. ### Common errors
    A number of examples of common errors are captured in the common errors doc.
diff --git a/OEM_SCHEMAS.md b/OEM_SCHEMAS.md
new file mode 100644
index 0000000000..275b6c2423
--- /dev/null
+++ b/OEM_SCHEMAS.md
@@ -0,0 +1,72 @@
+## Redfish OEM Resources
+
+The Redfish specification allows for OEM resources and properties to be
+implemented by OEMs.  As a general rule, OpenBMC discourages the use of OEM
+namespaces in APIs.  In line with this, bmcweb does not expose an API for adding
+OEM properties in a backward API compatible way for resources that have not been
+merged to master.
+
+### Why?
+OEM properties in an open source project pose many problems when compared to
+their closed source brethren in terms of reliability, code reuse, compatibility,
+and maintenance.
+
+1. As a general rule, OpenBMCs external Redfish API aims to be as compatible
+   between systems as possible.  Adding machine-specific resources, properties,
+   and types largely defeats some of that goal, as clients must implement
+   machine-specific APIs, some of which are likely to overlap, which increases
+   the amount of code overall.  OpenBMC also has very little visibility into
+   clients that might interface with Redfish, and therefore needs to take care
+   when adding new, non-standard APIs.
+
+2. In practice, OEM resources trend toward a lower level of quality and testing
+   than their spec-driven alternatives, given the lack of available systems to
+   test on, and the limited audience of both producers and consumers. This poses
+   a problem for maintenance in the long run, as it is very difficult to make a
+   breaking change to an external API, given that clients are likely to be
+   implemented in projects that OpenBMC isn't aware of.
+
+3. If a given workflow eventually becomes standardized, OpenBMC OEM endpoints
+   now have to break an API boundary to be able to move to the standard
+   implementation.  Given the amount of effort it takes to break an API, it is
+   much simpler to wait for the standard to be completed before merging the OEM
+   code to master.
+
+4. DMTF has many more Redfish experts than OpenBMC.  While the bmcweb
+   maintainers do their best to stay current on the evolving Redfish ecosystem,
+   we have significantly limited scope, knowledge, and influence over the
+   standard when compared to the experts within DMTF.  Getting a DMTF opinion
+   almost always leads to positive API design changes up front, which increases
+   the usefulness of the code we write within the industry.
+
+### How?
+
+If you've read the above, and still think an OEM property is warranted, please
+take the following steps.
+
+1. Present the new feature and use case to DMTF either through the [Redfish
+   forum](https://www.redfishforum.com), or at a DMTF meeting.  If possible,
+   message the new feature through the normal openbmc communications channels to
+   ensure OpenBMC is properly represented in the meeting/forum.
+2. If DMTF is interested in the proposal, proceed using their documented process
+   for change requests, and get your schema changes standardized;  While OpenBMC
+   does not merge new schemas that have not been ratified by DMTF, feel free to
+   push them to gerrit.  If the features are major enough to warrant it, feel
+   free to discuss with maintainers about hosting a branch within gerrit while
+   your DMTF proposal is in progress.  If the DMTF feedback is documented as
+   something to the effect of "this use case is unique to OpenBMC", proceed to
+   write an OpenBMC design document about the new feature you intend to
+   implement as OEM, under the OpenBMC (generic to all platforms) OEM namespace.
+3. If OpenBMC feedback is that this feature is specific to a single OEM or ODM,
+   and is unlikely to be used across platforms, then maintainers will provide
+   you the option of adding your feature under an OEM/ODM specific namespace.
+
+Regardless of the OEM namespace being used, implementations should plan to
+implement all appropriate CSDL and OpenAPI schemas for their given OEM
+resources, should pass the redfish service validator, and should follow redfish
+API design practices.  We require this same level of quality as non OEM to
+ensure that OEM is truly required by the contributor to satisfy their use case.
+If OEM were held to a lesser level of quality requirements, bwcweb would consist
+entirely of OEM code.
+
+bmcweb maintainers retain the final approval on OEM schemas.