Document expectations for commit messages

This commit tries to be more explicit about the expectations for commit
messages and testing within bmcweb, and give maintainers something to
point to instead of repeating the same statements over and over again.

This will likely need to evolve, but I think it's a good start, and
would help people put together commits that can be merged on the first
try, rather than requiring followup.

Tested: Documentation only, no testing.

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

1 files changed, 50 insertions, 0 deletions

diff --git a/DEVELOPING.md b/DEVELOPING.md
index 1a9712a258..fcd5b3a8a8 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -126,6 +126,56 @@
    starting any openbmc development.
    [Common Errors](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md).
 
+14. ### Commit messages
+   Project commit message formatting should be obeyed
+   [link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages)
+
+   Commit messages should answer the following questions:
+   - Why are the changes useful?  Given that bmcweb is a user-facing daemon,
+      commits adding new functionality should include statements about how the
+      commit in question is useful to the user.
+
+   - What changes would a user expect to see?  This includes new parameters, new
+     resources, and new or changed properties.  Any route changes should be
+     explicitly called out.
+
+   - Are there compatibility concerns?  Is this change backward compatible for
+     clients?  If not, what commit would be broken, and how old is it?   Have
+     clients been warned? (ideally on the mailing list) link the discussion.
+
+   Commit messages should be line wrapped 50/72.
+
+15. ### Compatibility
+   "Don't make your users mad" Greg K-H
+   [source](https://git.sr.ht/~gregkh/presentation-application_summit/tree/main/keep_users_happy.pdf)
+
+   The kernel has very similar rules around compatibility that we should aspire
+   to follow in the footsteps of.
+
+   To that end, bmcweb will do its' best to insulate clients from breaking api
+   changes.  Being explicit about this ensures that clients can upgrade their
+   OpenBMC version without issue, and resolves a significant bottleneck in
+   getting security patches deployed to users.  Any change that's visible to a
+   user is potentially a breaking change, but requiring _all_ visible changes to
+   be configurable would increase the software complexity, therefore bmcweb
+   makes exceptions for things which a client is reasonably expected to code
+   against:
+   - New items added to a collection
+   - Changes in UID for hypermedia resources (In line with Redfish spec)
+   - New properties added to a resource
+   - New versions of a given schema
+
+   Special note: Code exists in bmcweb that is missing upstream backends to
+   make it function.  Given that compatibility requires the ability to use and
+   test the feature in question, changes to these methods, including outright
+   removal, does not constitute a breaking change.
+
+   Security: There may be cases where maintainers make explicit breaking changes
+   in the best interest of security;  In these rare cases, the maintainers and
+   contributors will endeavor to avoid breaking clients as much as is
+   technically possible, but as with all security, impact will need to be
+   weighed against the security impact of not making changes, and judgement
+   calls will be made, with options to allow providing the old behavior.
 
 ## clang-tidy