Proposal: how to make incompatible changes

[Joseph Reynolds]

Proposal: how to make incompatible changes

This is a proposal to add guidelines for making incompatible changes to 
OpenBMC interfaces.  Is it okay to make incompatible changes? Yes, IMHO: 
the project will continuously break compatibility in various ways, and 
its users will adapt.  The main idea is to minimize churn and make it 
easier for users to adapt.

As the OpenBMC project moves forward with new releases, it will make 
changes that necessarily break existing use cases.  My recommendations are:
- Try hard to maintain forward compatibility.  For example, maintain all 
of the BMC's intended user interfaces.
- Identify changes that break compatibility.  Briefly describe the use 
case, what breaks, how a user can adapt, and cross-link technical 
discussions (Gerrit reviews, issues, emails).
- Work with maintainers to determine which incompatible changes get 
merged and what documentation is needed.
- Give users time to adapt to incompatible changes.  For example, 
deprecate interfaces in a previous release.
- List incompatible changes in the [release notes][] so community 
members will know they have to adapt, and link to how to adapt.

[release notes]: 
https://github.com/openbmc/docs/blob/master/release/release-notes

Perhaps we could add a section to one of these here documents:
https://github.com/openbmc/docs/blob/master/maintainer-workflow.md
https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md

What do you think?

- Joseph


TLDR:

Applicability.

These guidelines are for the BMC's "intended external user interfaces".  
For example, its management interfaces including its web server and all 
REST APIs.  I haven't given much thought to the BMC/host interfaces or 
interfaces internal to the BMC.  IMHO, it is less important to maintain 
compatibility in these areas.  For example, if you need an incompatible 
change in an internal interface, you have a smaller set of users who 
ought to be active in the project, and can give you feedback and adapt 
within a release cycle.


What is forward compatibility?

The OpenBMC project has a sequence of releases.  When someone is using 
one of these releases, then updates to a later release, ideally all the 
BMC interfaces they use will continue to work as before.  That's what I 
call "forward compatibility"  which is close to the Wikipedia's [upward 
compatibility][].

Backward compatibility means that after you perform a firmware update to 
an older release in the sequence, using that release's older interfaces 
will continue to operate the BMC as before.  That is, you can downgrade 
to that release.  For example, backward compatibility is needed to be 
able to revert a previous update back to a known-good firmware image 
version.  Once again, this is different from Wikipedia's [backward 
compatibility][] entry which is more like interoperability.

I think it is useful to separate these concepts.  To be clear: I am in 
favor of the OpenBMC interfaces being upward compatible, backward 
compatible, and interoperable, but I think we need to take baby steps to 
get there.  So I am limiting the scope of this email to a narrow 
definition of forward compatibility.

I expect maintainers will consider backward compatibility at the same 
time they consider forward compatibility.  Note that it may be 
acceptable to break backward compatibility more frequently that breaking 
forward compatibility.  For example, you can tell users that once they 
upgrade to a new release, they cannot downgrade.

[upward compatibility]: https://en.wikipedia.org/wiki/Forward_compatibility
[backward compatibility]: 
https://en.wikipedia.org/wiki/Backward_compatibility


Examples of changes that may break compatibility:

https://gerrit.openbmc-project.xyz/c/openbmc/pam-ipmi/+/31054

https://github.com/openbmc/openbmc/issues/3615

https://gerrit.openbmc-project.xyz/c/openbmc/bmcweb/+/29344