Proposal: how to make incompatible changes - versioning
Joseph Reynolds
jrey at linux.ibm.com
Fri Apr 24 01:57:03 AEST 2020
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?
- Joseph
> Alexander.
>
More information about the openbmc
mailing list