Proposal: how to make incompatible changes - versioning
Andrew Jeffery
andrew at aj.id.au
Sat Apr 25 10:23:52 AEST 2020
On Fri, 24 Apr 2020, at 01:27, Joseph Reynolds wrote:
> On 4/23/20 7:11 AM, Alexander Amelkin wrote:
> > 15.04.2020 02:00, 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.
> >>
> >>
> > I'd say that any incompatible change must be reflected in the
> > interface version.
> >
> > As far as I understand, RedFish has all the interfaces strictly
> > specified and those specifications are bound to a specific RedFish
> > version that is then encoded in the URL (e.g. /redfish/v1/).
> >
> > Any other interface should have a similar approach. A more relaxed
> > one, if we keep our own flavor of REST, could be that each interface
> > could have a Version property (probably also encoded in the REST URL).
> >
> > That way, any user trying to access an old interface (thus via a
> > non-existant URL) would get a 404.
> >
> > Internally, for inter-process dbus communication the interface version
> > could be checked during compile time to prevent problems that couldn't
> > be detected by compiler/linker automatically. Those problems are, for
> > instance, incompatible change in the meaning of the values of a property.
>
> Agreed. The question to ponder: What is our REST API versioning
> strategy? What best practices do we follow?
The D-Bus specification already recommends how to version D-Bus interfaces:
https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface
Andrew
More information about the openbmc
mailing list