I agree with this proposal. Some clarification needed. The ODP API major.minor version will only change at well-defined release points, not for every commit. Between releases, the API may change (including incompatible changes) without this being reflected in the API version.
- Ola On 23 September 2014 22:53, Mike Holmes <[email protected]> wrote: > Is there any follow on from connect on this thread ? > I realise Taras is out but can we all converge on the final wording for a > three level configuration ? > All this is from the application writers perspective and not from the > PLATFORM implementers perspective, it ONLY describes the API, not > infrastructure changes. > > 'major.minor.sub ' > > The *major* digit is the ODP API generation. > It would be used generally to indicate backward incompatibility, a change > to this digit will break backwards compatibility > > - Altering API signature > - Altering a structure > - Changing the required calling sequence for APIs > - Changes to the installed structure > - New element to an enum that is an output from ODP > > The *minor* digit is for changes that are probably backwards compatible. > Things such as the the addition of a new API. Existing application code > probably does not have to change. > Any existing app should not need to change any calls and it should > continue to compile with the new ODP API version > > - Adding a new struct > - Adding a new function > - Adding an additional alternate API to an existing one. > - New element to an enum that is an input to ODP > > *The first two digits indicate (potential) backward incompatibility, only > ODP (the community) can update these two numbers. * > > The *sub* digit is used for backward compatible changes > Any existing app should work as before with the caveat that a bug fix may > change the executable behavior (hopefully improve it) > > - Optimize the implementation > - Documentation updates > - Whitespace > - bug fixes in implementation > > > > On 11 September 2014 09:00, Ola Liljedahl <[email protected]> > wrote: > >> Taras: >> - 'sub' is a version that must be incremented on each *incompatible* >> API change (syntax or semantics) between releases. It is reset on >> each major.minor change. >> You mean "compatible"? >> >> I think it makes sense to change the API version also when making >> backwards compatible changes. E.g. if we are adding a function or some >> parameter flag but this is not worthy of a major.minor increment. An >> application might want to know if a specific function or feature is >> available. >> >> Petri: >> This is not equivalent to Mike's description where only the major number >> would be changed for incompatible changes where you write that the first >> two digits (or numbers) indicate (potential) backward incompatibility. >> >> I think your definition is the best. I also think the description needs >> to include what promises are made to the users (the applications), e.g. >> your two last sentences, otherwise the definition is going to be too >> abstract and we will come back and argue what the version numbers really >> means. In the mean time, changes will have been made that violate the >> versioning scheme. >> >> >> >> On 11 September 2014 09:25, Savolainen, Petri (NSN - FI/Espoo) < >> [email protected]> wrote: >> >>> Hi, >>> >>> Agree with Taras on three levels. It's there in odp_version.h already, >>> but we may need to revise the comments a bit. >>> >>> The main digit must be reserved for ODP API generations (major >>> reorganizations, etc). If it would be used only to indicate backward >>> incompatibility, we'd be in ODP 15.0 in couple of months... Similarly I see >>> that after 1.0 comes 1.1 (2.0 would be major rework of the whole thing). >>> >>> So, first two digits indicate (potential) backward incompatibility. >>> Third one can be used for backward compatible changes (small additions, bug >>> fixes, missing doxygen comments, documentation bugs, white spaces, etc). >>> The point being that if all three are the same, it's 100% the same. If >>> first two are the same, application compiles and runs without any change. >>> >>> -Petri >>> >>> >>> > -----Original Message----- >>> > From: ext Taras Kondratiuk [mailto:[email protected]] >>> > Sent: Wednesday, September 10, 2014 6:10 PM >>> > To: Ola Liljedahl; Mike Holmes >>> > Cc: Savolainen, Petri (NSN - FI/Espoo); Taras Kondratiuk; lng- >>> > [email protected] >>> > Subject: Re: [lng-odp] [PATCH] linux-generic: version: Add macros to >>> > compare ODP versions >>> > >>> > On 09/10/2014 05:35 PM, Ola Liljedahl wrote: >>> > > I think we should separate between ODP implementations and the ODP >>> API. >>> > > Users (applications) are primarily interested in the API. Any API >>> > > changes can be separated into backwards and not backwards compatible >>> > > changes. I think a major.minor designation for the ODP API is >>> sufficient >>> > > (there is no patch level of the API specification or?). The major >>> number >>> > > changes for any incompatible changes (with minor number reset), the >>> > > minor number changes for any backwards compatible change (with major >>> > > number kept). Small or big change is not relevant. >>> > >>> > I had in mind a bit different schema: major.minor.sub. >>> > - 'major.minor' is an official ODP release version, like v1.0 we are >>> > going to have by EOY. >>> > - 'sub' is a version that must be incremented on each incompatible >>> > API change (syntax or semantics) between releases. It is reset on >>> > each major.minor change. >>> > >>> > IMO there is no point to change API version for backward compatible >>> > changes. >>> > >>> > > >>> > > One can imagine an application that attempts to handle changes (bugs >>> and >>> > > bug fixes) in the ODP implementation by checking which version >>> > > (including the C number as defined below) the implementation is at. >>> But >>> > > this will be difficult with ODP since there will be multiple >>> > > implementations and those can and will likely have different version >>> > > sequences. The application would also need a mean to identify which >>> ODP >>> > > implementation it is using. >>> > >>> > Currently ODP_VERSION_API* macros address only API versions. >>> > Adding versions for implementation is a separate story. To use it we >>> > may need a way for application to detect which implementation is used. >>> > Maybe expose define like ODP_PLATFORM_LINUX_GENERIC. >>> >> >> > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP >
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
