| Message ID | 1412015096-62424-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Rejected |
| Headers | show |
Looks good to me. +1 On Mon, Sep 29, 2014 at 1:24 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- > release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the above. > + > +The header file odp_version.h contains helper macros for dealing with > ODP versions in application code. > + > +@note The version refers to API source compatibility and not binary > compatibility. > +Every change in API version will require a recompilation, relinking will > not be sufficient. > + > +The ODP API major.minor version will only change at well-defined release > points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix > releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> > @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards compatibility. > +@note The incompatibility covers the whole ODP API, however the change > may be a tiny change to an esoteric function that is not used by a given > application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make install" > moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new API is not > used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation > + > + > +*/ > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
On Mon, Sep 29, 2014 at 1:24 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the above. > + > +The header file odp_version.h contains helper macros for dealing with > ODP versions in application code. > + > +@note The version refers to API source compatibility and not binary > compatibility. > +Every change in API version will require a recompilation, relinking will > not be sufficient. > + > +The ODP API major.minor version will only change at well-defined release > points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix > releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> > @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards compatibility. > +@note The incompatibility covers the whole ODP API, however the change > may be a tiny change to an esoteric function that is not used by a given > application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make install" > moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new API is not > used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation > + > + > +*/ > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
ping - Stuart are you now happy with this now ? On 29 September 2014 14:34, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > On Mon, Sep 29, 2014 at 1:24 PM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > >> --- >> release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 54 insertions(+) >> create mode 100644 release.dox >> >> diff --git a/release.dox b/release.dox >> new file mode 100644 >> index 0000000..53301ac >> --- /dev/null >> +++ b/release.dox >> @@ -0,0 +1,54 @@ >> +/* Copyright (c) 2014, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page release Release Management >> +@tableofcontents >> +@section release_numbering Numbering >> + >> +The API uses a three digit release number, for ODP this number refers to >> +- The API header definitions >> +- The reference implementation (linux-generic) >> +- The documentation >> +- The API test & validation suite that certifies each of the above. >> + >> +The header file odp_version.h contains helper macros for dealing with >> ODP versions in application code. >> + >> +@note The version refers to API source compatibility and not binary >> compatibility. >> +Every change in API version will require a recompilation, relinking will >> not be sufficient. >> + >> +The ODP API major.minor version will only change at well-defined release >> points. >> +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix >> releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> >> @endcode first bug fix release sub = 1. >> + >> +@subsection major Major >> +The major digit is the ODP API generation. >> +A change to this digit indicates a break in backwards compatibility. >> +@note The incompatibility covers the whole ODP API, however the change >> may be a tiny change to an esoteric function that is not used by a given >> application. >> + >> +- Altering API signature >> +- Altering a structure other than adding optional items at the end. >> +- Changing the required calling sequence for APIs >> +- Changes to the installed structure i.e. the output from "make install" >> moves a file in a way that breaks compilation. >> +- New element to an enum that is an output from ODP >> + >> +@subsection minor Minor >> +The minor digit is for changes that are backwards compatible. >> +For example changes such as the addition of a new API. >> +Existing application code shall not have to change if the new API is not >> used. >> +- 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 >> + >> +@subsection sub Sub >> +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 >> +- bug fixes in implementation >> + >> + >> +*/ >> -- >> 1.9.1 >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> > >
On Thu, Oct 02, 2014 at 12:43:47PM +0100, Mike Holmes wrote: > ping - Stuart are you now happy with this now ? > Yes, looks good. Reviewed-by: Stuart Haslam <stuart.haslam@arm.com> > On 29 September 2014 14:34, Bill Fischofer <bill.fischofer@linaro.org<mailto:bill.fischofer@linaro.org>> wrote: > > > On Mon, Sep 29, 2014 at 1:24 PM, Mike Holmes <mike.holmes@linaro.org<mailto:mike.holmes@linaro.org>> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org<mailto:mike.holmes@linaro.org>> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org<mailto:bill.fischofer@linaro.org>> > --- > release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the above. > + > +The header file odp_version.h contains helper macros for dealing with ODP versions in application code. > + > +@note The version refers to API source compatibility and not binary compatibility. > +Every change in API version will require a recompilation, relinking will not be sufficient. > + > +The ODP API major.minor version will only change at well-defined release points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards compatibility. > +@note The incompatibility covers the whole ODP API, however the change may be a tiny change to an esoteric function that is not used by a given application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make install" moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new API is not used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation > + > + > +*/ > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org<mailto:lng-odp@lists.linaro.org> > http://lists.linaro.org/mailman/listinfo/lng-odp > > > > > -- > Mike Holmes > Linaro Sr Technical Manager > LNG - ODP > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
On 09/29/2014 09:24 PM, Mike Holmes wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the above. > + > +The header file odp_version.h contains helper macros for dealing with ODP versions in application code. > + > +@note The version refers to API source compatibility and not binary compatibility. > +Every change in API version will require a recompilation, relinking will not be sufficient. > + > +The ODP API major.minor version will only change at well-defined release points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards compatibility. > +@note The incompatibility covers the whole ODP API, however the change may be a tiny change to an esoteric function that is not used by a given application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make install" moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new API is not used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation That is a version of API and should not be related to any implementation. > + > +*/ > IMO having only Major number for backward incompatible changes is not enough. I assume each our release during the next year won't be backward compatible, so we will bump major number too often. I imagine versions in a following way: 1. Major: - Major architectural changes like buffer/packet managements changes - new big sets of API added 2. Minor: your description for 'major' version 3. Sub: your description for 'minor' version + Documentation updates
On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > On 09/29/2014 09:24 PM, Mike Holmes wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 54 insertions(+) >> create mode 100644 release.dox >> >> diff --git a/release.dox b/release.dox >> new file mode 100644 >> index 0000000..53301ac >> --- /dev/null >> +++ b/release.dox >> @@ -0,0 +1,54 @@ >> +/* Copyright (c) 2014, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page release Release Management >> +@tableofcontents >> +@section release_numbering Numbering >> + >> +The API uses a three digit release number, for ODP this number refers to >> +- The API header definitions >> +- The reference implementation (linux-generic) >> +- The documentation >> +- The API test & validation suite that certifies each of the above. >> + >> +The header file odp_version.h contains helper macros for dealing with >> ODP versions in application code. >> + >> +@note The version refers to API source compatibility and not binary >> compatibility. >> +Every change in API version will require a recompilation, relinking will >> not be sufficient. >> + >> +The ODP API major.minor version will only change at well-defined release >> points. >> +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix >> releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> >> @endcode first bug fix release sub = 1. >> + >> +@subsection major Major >> +The major digit is the ODP API generation. >> +A change to this digit indicates a break in backwards compatibility. >> +@note The incompatibility covers the whole ODP API, however the change >> may be a tiny change to an esoteric function that is not used by a given >> application. >> + >> +- Altering API signature >> +- Altering a structure other than adding optional items at the end. >> +- Changing the required calling sequence for APIs >> +- Changes to the installed structure i.e. the output from "make install" >> moves a file in a way that breaks compilation. >> +- New element to an enum that is an output from ODP >> + >> +@subsection minor Minor >> +The minor digit is for changes that are backwards compatible. >> +For example changes such as the addition of a new API. >> +Existing application code shall not have to change if the new API is not >> used. >> +- 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 >> + >> +@subsection sub Sub >> +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 >> +- bug fixes in implementation >> > > That is a version of API and should not be related to any > implementation. > > + >> +*/ >> >> > IMO having only Major number for backward incompatible changes is not > enough. I assume each our release during the next year won't be backward > compatible, so we will bump major number too often. > What does too often mean ? The Linux major number is worthless, it only changes when Linus decides he wants a change, it means nothing. GCC has been around since T-Rex (Cretaceous period) ate Triceratops for breakfast and they only made it to 4.x, so far is that good or is it bad ? The important thing is that you know what a change in number means not that it is a big or little number. > I imagine versions in a following way: > > 1. Major: > - Major architectural changes like buffer/packet managements changes > - new big sets of API added > > 2. Minor: your description for 'major' version > > 3. Sub: your description for 'minor' version + Documentation updates >
> -----Original Message----- > From: ext Taras Kondratiuk [mailto:taras.kondratiuk@linaro.org] > Sent: Thursday, October 02, 2014 6:56 PM > To: Mike Holmes; lng-odp@lists.linaro.org > Cc: Petri Savolainen > Subject: Re: [lng-odp] [ARCH PATCH v3] Add release management > > On 09/29/2014 09:24 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > > --- > > release.dox | 54 > ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 54 insertions(+) > > create mode 100644 release.dox > > > > diff --git a/release.dox b/release.dox > > new file mode 100644 > > index 0000000..53301ac > > --- /dev/null > > +++ b/release.dox > > @@ -0,0 +1,54 @@ > > +/* Copyright (c) 2014, Linaro Limited > > + * All rights reserved > > + * > > + * SPDX-License-Identifier: BSD-3-Clause > > + */ > > + > > +/** > > +@page release Release Management > > +@tableofcontents > > +@section release_numbering Numbering > > + > > +The API uses a three digit release number, for ODP this number refers > to > > +- The API header definitions > > +- The reference implementation (linux-generic) > > +- The documentation > > +- The API test & validation suite that certifies each of the above. > > + > > +The header file odp_version.h contains helper macros for dealing with > ODP versions in application code. > > + > > +@note The version refers to API source compatibility and not binary > compatibility. > > +Every change in API version will require a recompilation, relinking > will not be sufficient. > > + > > +The ODP API major.minor version will only change at well-defined > release points. > > +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix > releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> > @endcode first bug fix release sub = 1. > > + > > +@subsection major Major > > +The major digit is the ODP API generation. > > +A change to this digit indicates a break in backwards compatibility. > > +@note The incompatibility covers the whole ODP API, however the change > may be a tiny change to an esoteric function that is not used by a given > application. > > + > > +- Altering API signature > > +- Altering a structure other than adding optional items at the end. > > +- Changing the required calling sequence for APIs > > +- Changes to the installed structure i.e. the output from "make > install" moves a file in a way that breaks compilation. > > +- New element to an enum that is an output from ODP > > + > > +@subsection minor Minor > > +The minor digit is for changes that are backwards compatible. > > +For example changes such as the addition of a new API. > > +Existing application code shall not have to change if the new API is > not used. > > +- 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 > > + > > +@subsection sub Sub > > +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 > > +- bug fixes in implementation > > That is a version of API and should not be related to any > implementation. > > > + > > +*/ > > > > IMO having only Major number for backward incompatible changes is not > enough. I assume each our release during the next year won't be backward > compatible, so we will bump major number too often. > > I imagine versions in a following way: > > 1. Major: > - Major architectural changes like buffer/packet managements changes > - new big sets of API added > > 2. Minor: your description for 'major' version > > 3. Sub: your description for 'minor' version + Documentation updates Totally agree with Taras here. I have been trying to get the same message through multiple times already. Most changes in the API during the next year or so will contain some backward incompatibility. E.g. when adding a new API we may need to change some exiting APIs so that those fit nicely together. Also even the smallest change in API documentation, may require changes in application code (the contract changed). We should release often (once per month/quarter ) and not worry about backward compatibility yet. Major digit must be reserved for fundamental changes in architecture (sync vs async APIs, role of queues/scheduling, etc) or feature set (higher layer abstractions, frameworks, etc). Lastly, why this definition should be maintained both in arch and API documentation. I'd maintain only one copy - in odp_version.h. -Petri
On 10/02/2014 11:12 PM, Mike Holmes wrote: > > > On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org > <mailto:taras.kondratiuk@linaro.org>> wrote: > > On 09/29/2014 09:24 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > --- > release.dox | 54 > ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number > refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the above. > + > +The header file odp_version.h contains helper macros for > dealing with ODP versions in application code. > + > +@note The version refers to API source compatibility and not > binary compatibility. > +Every change in API version will require a recompilation, > relinking will not be sufficient. > + > +The ODP API major.minor version will only change at > well-defined release points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and > bug fix releases on the platform will be tagged @code > ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards > compatibility. > +@note The incompatibility covers the whole ODP API, however the > change may be a tiny change to an esoteric function that is not > used by a given application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make > install" moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new > API is not used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation > > > That is a version of API and should not be related to any > implementation. > > + > +*/ > > > IMO having only Major number for backward incompatible changes is not > enough. I assume each our release during the next year won't be > backward compatible, so we will bump major number too often. > > > What does too often mean ? > The Linux major number is worthless, it only changes when Linus decides > he wants a change, it means nothing. Linux is not a good example because it has different release policy. Linus doesn't set/communicate expectations on what is included in which release. But we do by saying that v1.x is kind of evaluation-ready and v2.x will be production-ready. > GCC has been around since T-Rex (Cretaceous period) ate Triceratops > for breakfast and they only made it to 4.x, so far is that good or is > it bad ? > > The important thing is that you know what a change in number means not > that it is a big or little number. That's an important thing why I'd like to have two numbers for backward incompatible changes. Two number gives more granularity to describe a 'size' of incompatibility. Let's say in one number case it is not clear what amount of changes need to be done to migrate from version 12 to 13 of ODP API. But in two number case I'd expect that minor version change will need only a few percent of application code touched. While major number change may cause a complete application redesign. Also I expect we will end up having LTS branches for each major release number, because developers may not want to do significant redesign of their application, but want to use some features added in new versions.
Taras, Petri, please propose a patch with alternate wording. If we want to put the text in the API file that is fine with me. I think we should give it a module name though so that it becomes a highlighted section in the doc and not buried inside that files documentation. Mike On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > On 10/02/2014 11:12 PM, Mike Holmes wrote: > >> >> >> On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org >> <mailto:taras.kondratiuk@linaro.org>> wrote: >> >> On 09/29/2014 09:24 PM, Mike Holmes wrote: >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org >> <mailto:mike.holmes@linaro.org>> >> --- >> release.dox | 54 >> ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ >> >> 1 file changed, 54 insertions(+) >> create mode 100644 release.dox >> >> diff --git a/release.dox b/release.dox >> new file mode 100644 >> index 0000000..53301ac >> --- /dev/null >> +++ b/release.dox >> @@ -0,0 +1,54 @@ >> +/* Copyright (c) 2014, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page release Release Management >> +@tableofcontents >> +@section release_numbering Numbering >> + >> +The API uses a three digit release number, for ODP this number >> refers to >> +- The API header definitions >> +- The reference implementation (linux-generic) >> +- The documentation >> +- The API test & validation suite that certifies each of the >> above. >> + >> +The header file odp_version.h contains helper macros for >> dealing with ODP versions in application code. >> + >> +@note The version refers to API source compatibility and not >> binary compatibility. >> +Every change in API version will require a recompilation, >> relinking will not be sufficient. >> + >> +The ODP API major.minor version will only change at >> well-defined release points. >> +A release will be tagged @code ODP-<major>.<minor> @endcode and >> bug fix releases on the platform will be tagged @code >> ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. >> + >> +@subsection major Major >> +The major digit is the ODP API generation. >> +A change to this digit indicates a break in backwards >> compatibility. >> +@note The incompatibility covers the whole ODP API, however the >> change may be a tiny change to an esoteric function that is not >> used by a given application. >> + >> +- Altering API signature >> +- Altering a structure other than adding optional items at the >> end. >> +- Changing the required calling sequence for APIs >> +- Changes to the installed structure i.e. the output from "make >> install" moves a file in a way that breaks compilation. >> +- New element to an enum that is an output from ODP >> + >> +@subsection minor Minor >> +The minor digit is for changes that are backwards compatible. >> +For example changes such as the addition of a new API. >> +Existing application code shall not have to change if the new >> API is not used. >> +- 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 >> + >> +@subsection sub Sub >> +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 >> +- bug fixes in implementation >> >> >> That is a version of API and should not be related to any >> implementation. >> >> + >> +*/ >> >> >> IMO having only Major number for backward incompatible changes is not >> enough. I assume each our release during the next year won't be >> backward compatible, so we will bump major number too often. >> >> >> What does too often mean ? >> The Linux major number is worthless, it only changes when Linus decides >> he wants a change, it means nothing. >> > > Linux is not a good example because it has different release policy. > Linus doesn't set/communicate expectations on what is included in which > release. But we do by saying that v1.x is kind of evaluation-ready and > v2.x will be production-ready. > > GCC has been around since T-Rex (Cretaceous period) ate Triceratops >> for breakfast and they only made it to 4.x, so far is that good or is >> it bad ? >> >> The important thing is that you know what a change in number means not >> that it is a big or little number. >> > > That's an important thing why I'd like to have two numbers for backward > incompatible changes. Two number gives more granularity to describe a > 'size' of incompatibility. Let's say in one number case it is not clear > what amount of changes need to be done to migrate from version 12 to 13 > of ODP API. But in two number case I'd expect that minor version change > will need only a few percent of application code touched. While major > number change may cause a complete application redesign. > > Also I expect we will end up having LTS branches for each major release > number, because developers may not want to do significant redesign of > their application, but want to use some features added in new versions. >
There seems to be some continuing confusion as to what constitutes an ODP Release. To date we've had exactly two: v0.1 released December 2013, and v0.2 released March 2014. We also stated there would be no API compatibility claims prior to v1.0. An ODP Release is a tag on the repository that denotes a specific set of (documented) functionality. Right now the only Releases planned by this definition are v1.0 planned for December 2014 and v2.0 planned for December 2015. The "live" ODP git tree is not a release and those working with the tip have no guarantees of any API stability. All of this discussion relates to statements we make about tagged releases, not what happens at the tip on a day to day or month to month basis. If we choose to make a tagged release after v1.0 but before December 2015, we'll then pick a number based on the functional delta from the v1.0 base. If there's reason to tag a release in June 2015, for example, then we'll call it v1.x or v2.0 based on what's in it. If we wind up calling it v2.0 then what we tag in December 2015 will again be called either v2.x or v3.0 based on what's in it. Does that help? Bill On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Taras, Petri, please propose a patch with alternate wording. > > If we want to put the text in the API file that is fine with me. I think > we should give it a module name though so that it becomes a highlighted > section in the doc and not buried inside that files documentation. > > Mike > > On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org> > wrote: > >> On 10/02/2014 11:12 PM, Mike Holmes wrote: >> >>> >>> >>> On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org >>> <mailto:taras.kondratiuk@linaro.org>> wrote: >>> >>> On 09/29/2014 09:24 PM, Mike Holmes wrote: >>> >>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org >>> <mailto:mike.holmes@linaro.org>> >>> --- >>> release.dox | 54 >>> ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ >>> >>> 1 file changed, 54 insertions(+) >>> create mode 100644 release.dox >>> >>> diff --git a/release.dox b/release.dox >>> new file mode 100644 >>> index 0000000..53301ac >>> --- /dev/null >>> +++ b/release.dox >>> @@ -0,0 +1,54 @@ >>> +/* Copyright (c) 2014, Linaro Limited >>> + * All rights reserved >>> + * >>> + * SPDX-License-Identifier: BSD-3-Clause >>> + */ >>> + >>> +/** >>> +@page release Release Management >>> +@tableofcontents >>> +@section release_numbering Numbering >>> + >>> +The API uses a three digit release number, for ODP this number >>> refers to >>> +- The API header definitions >>> +- The reference implementation (linux-generic) >>> +- The documentation >>> +- The API test & validation suite that certifies each of the >>> above. >>> + >>> +The header file odp_version.h contains helper macros for >>> dealing with ODP versions in application code. >>> + >>> +@note The version refers to API source compatibility and not >>> binary compatibility. >>> +Every change in API version will require a recompilation, >>> relinking will not be sufficient. >>> + >>> +The ODP API major.minor version will only change at >>> well-defined release points. >>> +A release will be tagged @code ODP-<major>.<minor> @endcode and >>> bug fix releases on the platform will be tagged @code >>> ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. >>> + >>> +@subsection major Major >>> +The major digit is the ODP API generation. >>> +A change to this digit indicates a break in backwards >>> compatibility. >>> +@note The incompatibility covers the whole ODP API, however the >>> change may be a tiny change to an esoteric function that is not >>> used by a given application. >>> + >>> +- Altering API signature >>> +- Altering a structure other than adding optional items at the >>> end. >>> +- Changing the required calling sequence for APIs >>> +- Changes to the installed structure i.e. the output from "make >>> install" moves a file in a way that breaks compilation. >>> +- New element to an enum that is an output from ODP >>> + >>> +@subsection minor Minor >>> +The minor digit is for changes that are backwards compatible. >>> +For example changes such as the addition of a new API. >>> +Existing application code shall not have to change if the new >>> API is not used. >>> +- 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 >>> + >>> +@subsection sub Sub >>> +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 >>> +- bug fixes in implementation >>> >>> >>> That is a version of API and should not be related to any >>> implementation. >>> >>> + >>> +*/ >>> >>> >>> IMO having only Major number for backward incompatible changes is not >>> enough. I assume each our release during the next year won't be >>> backward compatible, so we will bump major number too often. >>> >>> >>> What does too often mean ? >>> The Linux major number is worthless, it only changes when Linus decides >>> he wants a change, it means nothing. >>> >> >> Linux is not a good example because it has different release policy. >> Linus doesn't set/communicate expectations on what is included in which >> release. But we do by saying that v1.x is kind of evaluation-ready and >> v2.x will be production-ready. >> >> GCC has been around since T-Rex (Cretaceous period) ate Triceratops >>> for breakfast and they only made it to 4.x, so far is that good or is >>> it bad ? >>> >>> The important thing is that you know what a change in number means not >>> that it is a big or little number. >>> >> >> That's an important thing why I'd like to have two numbers for backward >> incompatible changes. Two number gives more granularity to describe a >> 'size' of incompatibility. Let's say in one number case it is not clear >> what amount of changes need to be done to migrate from version 12 to 13 >> of ODP API. But in two number case I'd expect that minor version change >> will need only a few percent of application code touched. While major >> number change may cause a complete application redesign. >> >> Also I expect we will end up having LTS branches for each major release >> number, because developers may not want to do significant redesign of >> their application, but want to use some features added in new versions. >> > > > > -- > *Mike Holmes* > Linaro Sr Technical Manager > LNG - ODP > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp > >
I would add that our terminology to date might not be helping by using numbers to describe what are actually points in time. Thus echoing Bill, we should not call the planned releases by a release number especially after 1.0 as we may be forced to make a new release before a planned date. Thus the "2.0" planned release in December 2015 should just be called the 2015 December release or give it a codename, DEC15 anyone ? On 3 October 2014 08:23, Bill Fischofer <bill.fischofer@linaro.org> wrote: > There seems to be some continuing confusion as to what constitutes an ODP > Release. To date we've had exactly two: v0.1 released December 2013, and > v0.2 released March 2014. We also stated there would be no API > compatibility claims prior to v1.0. > > An ODP Release is a tag on the repository that denotes a specific set of > (documented) functionality. Right now the only Releases planned by this > definition are v1.0 planned for December 2014 and v2.0 planned for December > 2015. > > The "live" ODP git tree is not a release and those working with the tip > have no guarantees of any API stability. All of this discussion relates to > statements we make about tagged releases, not what happens at the tip on a > day to day or month to month basis. > > If we choose to make a tagged release after v1.0 but before December 2015, > we'll then pick a number based on the functional delta from the v1.0 base. > If there's reason to tag a release in June 2015, for example, then we'll > call it v1.x or v2.0 based on what's in it. If we wind up calling it v2.0 > then what we tag in December 2015 will again be called either v2.x or v3.0 > based on what's in it. > > Does that help? > > Bill > > On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Taras, Petri, please propose a patch with alternate wording. >> >> If we want to put the text in the API file that is fine with me. I think >> we should give it a module name though so that it becomes a highlighted >> section in the doc and not buried inside that files documentation. >> >> Mike >> >> On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org> >> wrote: >> >>> On 10/02/2014 11:12 PM, Mike Holmes wrote: >>> >>>> >>>> >>>> On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org >>>> <mailto:taras.kondratiuk@linaro.org>> wrote: >>>> >>>> On 09/29/2014 09:24 PM, Mike Holmes wrote: >>>> >>>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org >>>> <mailto:mike.holmes@linaro.org>> >>>> --- >>>> release.dox | 54 >>>> ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ >>>> >>>> 1 file changed, 54 insertions(+) >>>> create mode 100644 release.dox >>>> >>>> diff --git a/release.dox b/release.dox >>>> new file mode 100644 >>>> index 0000000..53301ac >>>> --- /dev/null >>>> +++ b/release.dox >>>> @@ -0,0 +1,54 @@ >>>> +/* Copyright (c) 2014, Linaro Limited >>>> + * All rights reserved >>>> + * >>>> + * SPDX-License-Identifier: BSD-3-Clause >>>> + */ >>>> + >>>> +/** >>>> +@page release Release Management >>>> +@tableofcontents >>>> +@section release_numbering Numbering >>>> + >>>> +The API uses a three digit release number, for ODP this number >>>> refers to >>>> +- The API header definitions >>>> +- The reference implementation (linux-generic) >>>> +- The documentation >>>> +- The API test & validation suite that certifies each of the >>>> above. >>>> + >>>> +The header file odp_version.h contains helper macros for >>>> dealing with ODP versions in application code. >>>> + >>>> +@note The version refers to API source compatibility and not >>>> binary compatibility. >>>> +Every change in API version will require a recompilation, >>>> relinking will not be sufficient. >>>> + >>>> +The ODP API major.minor version will only change at >>>> well-defined release points. >>>> +A release will be tagged @code ODP-<major>.<minor> @endcode and >>>> bug fix releases on the platform will be tagged @code >>>> ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = >>>> 1. >>>> + >>>> +@subsection major Major >>>> +The major digit is the ODP API generation. >>>> +A change to this digit indicates a break in backwards >>>> compatibility. >>>> +@note The incompatibility covers the whole ODP API, however the >>>> change may be a tiny change to an esoteric function that is not >>>> used by a given application. >>>> + >>>> +- Altering API signature >>>> +- Altering a structure other than adding optional items at the >>>> end. >>>> +- Changing the required calling sequence for APIs >>>> +- Changes to the installed structure i.e. the output from "make >>>> install" moves a file in a way that breaks compilation. >>>> +- New element to an enum that is an output from ODP >>>> + >>>> +@subsection minor Minor >>>> +The minor digit is for changes that are backwards compatible. >>>> +For example changes such as the addition of a new API. >>>> +Existing application code shall not have to change if the new >>>> API is not used. >>>> +- 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 >>>> + >>>> +@subsection sub Sub >>>> +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 >>>> +- bug fixes in implementation >>>> >>>> >>>> That is a version of API and should not be related to any >>>> implementation. >>>> >>>> + >>>> +*/ >>>> >>>> >>>> IMO having only Major number for backward incompatible changes is >>>> not >>>> enough. I assume each our release during the next year won't be >>>> backward compatible, so we will bump major number too often. >>>> >>>> >>>> What does too often mean ? >>>> The Linux major number is worthless, it only changes when Linus decides >>>> he wants a change, it means nothing. >>>> >>> >>> Linux is not a good example because it has different release policy. >>> Linus doesn't set/communicate expectations on what is included in which >>> release. But we do by saying that v1.x is kind of evaluation-ready and >>> v2.x will be production-ready. >>> >>> GCC has been around since T-Rex (Cretaceous period) ate Triceratops >>>> for breakfast and they only made it to 4.x, so far is that good or is >>>> it bad ? >>>> >>>> The important thing is that you know what a change in number means not >>>> that it is a big or little number. >>>> >>> >>> That's an important thing why I'd like to have two numbers for backward >>> incompatible changes. Two number gives more granularity to describe a >>> 'size' of incompatibility. Let's say in one number case it is not clear >>> what amount of changes need to be done to migrate from version 12 to 13 >>> of ODP API. But in two number case I'd expect that minor version change >>> will need only a few percent of application code touched. While major >>> number change may cause a complete application redesign. >>> >>> Also I expect we will end up having LTS branches for each major release >>> number, because developers may not want to do significant redesign of >>> their application, but want to use some features added in new versions. >>> >> >> >> >> -- >> *Mike Holmes* >> Linaro Sr Technical Manager >> LNG - ODP >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> >
We should release more often than once per year. A large application cannot be ported/developed/maintained on the development branch. It’s easier to follow multiple small steps, than e.g. port from v1.0 to v2.0 in one big bang. -Petri From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of ext Bill Fischofer Sent: Friday, October 03, 2014 3:24 PM To: Mike Holmes Cc: lng-odp Subject: Re: [lng-odp] [ARCH PATCH v3] Add release management There seems to be some continuing confusion as to what constitutes an ODP Release. To date we've had exactly two: v0.1 released December 2013, and v0.2 released March 2014. We also stated there would be no API compatibility claims prior to v1.0. An ODP Release is a tag on the repository that denotes a specific set of (documented) functionality. Right now the only Releases planned by this definition are v1.0 planned for December 2014 and v2.0 planned for December 2015. The "live" ODP git tree is not a release and those working with the tip have no guarantees of any API stability. All of this discussion relates to statements we make about tagged releases, not what happens at the tip on a day to day or month to month basis. If we choose to make a tagged release after v1.0 but before December 2015, we'll then pick a number based on the functional delta from the v1.0 base. If there's reason to tag a release in June 2015, for example, then we'll call it v1.x or v2.0 based on what's in it. If we wind up calling it v2.0 then what we tag in December 2015 will again be called either v2.x or v3.0 based on what's in it. Does that help? Bill On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org<mailto:mike.holmes@linaro.org>> wrote: Taras, Petri, please propose a patch with alternate wording. If we want to put the text in the API file that is fine with me. I think we should give it a module name though so that it becomes a highlighted section in the doc and not buried inside that files documentation. Mike On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org<mailto:taras.kondratiuk@linaro.org>> wrote: On 10/02/2014 11:12 PM, Mike Holmes wrote: On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org<mailto:taras.kondratiuk@linaro.org> <mailto:taras.kondratiuk@linaro.org<mailto:taras.kondratiuk@linaro.org>>> wrote: On 09/29/2014 09:24 PM, Mike Holmes wrote: Signed-off-by: Mike Holmes <mike.holmes@linaro.org<mailto:mike.holmes@linaro.org> <mailto:mike.holmes@linaro.org<mailto:mike.holmes@linaro.org>>> --- release.dox | 54 ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 release.dox diff --git a/release.dox b/release.dox new file mode 100644 index 0000000..53301ac --- /dev/null +++ b/release.dox @@ -0,0 +1,54 @@ +/* Copyright (c) 2014, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page release Release Management +@tableofcontents +@section release_numbering Numbering + +The API uses a three digit release number, for ODP this number refers to +- The API header definitions +- The reference implementation (linux-generic) +- The documentation +- The API test & validation suite that certifies each of the above. + +The header file odp_version.h contains helper macros for dealing with ODP versions in application code. + +@note The version refers to API source compatibility and not binary compatibility. +Every change in API version will require a recompilation, relinking will not be sufficient. + +The ODP API major.minor version will only change at well-defined release points. +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. + +@subsection major Major +The major digit is the ODP API generation. +A change to this digit indicates a break in backwards compatibility. +@note The incompatibility covers the whole ODP API, however the change may be a tiny change to an esoteric function that is not used by a given application. + +- Altering API signature +- Altering a structure other than adding optional items at the end. +- Changing the required calling sequence for APIs +- Changes to the installed structure i.e. the output from "make install" moves a file in a way that breaks compilation. +- New element to an enum that is an output from ODP + +@subsection minor Minor +The minor digit is for changes that are backwards compatible. +For example changes such as the addition of a new API. +Existing application code shall not have to change if the new API is not used. +- 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 + +@subsection sub Sub +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 +- bug fixes in implementation That is a version of API and should not be related to any implementation. + +*/ IMO having only Major number for backward incompatible changes is not enough. I assume each our release during the next year won't be backward compatible, so we will bump major number too often. What does too often mean ? The Linux major number is worthless, it only changes when Linus decides he wants a change, it means nothing. Linux is not a good example because it has different release policy. Linus doesn't set/communicate expectations on what is included in which release. But we do by saying that v1.x is kind of evaluation-ready and v2.x will be production-ready. GCC has been around since T-Rex (Cretaceous period) ate Triceratops for breakfast and they only made it to 4.x, so far is that good or is it bad ? The important thing is that you know what a change in number means not that it is a big or little number. That's an important thing why I'd like to have two numbers for backward incompatible changes. Two number gives more granularity to describe a 'size' of incompatibility. Let's say in one number case it is not clear what amount of changes need to be done to migrate from version 12 to 13 of ODP API. But in two number case I'd expect that minor version change will need only a few percent of application code touched. While major number change may cause a complete application redesign. Also I expect we will end up having LTS branches for each major release number, because developers may not want to do significant redesign of their application, but want to use some features added in new versions. -- Mike Holmes Linaro Sr Technical Manager LNG - ODP _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org<mailto:lng-odp@lists.linaro.org> http://lists.linaro.org/mailman/listinfo/lng-odp
It’s not a big deal if the dec 2015 release number is not 2.0. I’d prefer 1.x (whatever is the next digit at that time), since it would indicate we have _not_ made major architecture changes from 1.0. -Petri From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of ext Mike Holmes Sent: Friday, October 03, 2014 3:44 PM To: Bill Fischofer Cc: lng-odp Subject: Re: [lng-odp] [ARCH PATCH v3] Add release management I would add that our terminology to date might not be helping by using numbers to describe what are actually points in time. Thus echoing Bill, we should not call the planned releases by a release number especially after 1.0 as we may be forced to make a new release before a planned date. Thus the "2.0" planned release in December 2015 should just be called the 2015 December release or give it a codename, DEC15 anyone ? On 3 October 2014 08:23, Bill Fischofer <bill.fischofer@linaro.org<mailto:bill.fischofer@linaro.org>> wrote: There seems to be some continuing confusion as to what constitutes an ODP Release. To date we've had exactly two: v0.1 released December 2013, and v0.2 released March 2014. We also stated there would be no API compatibility claims prior to v1.0. An ODP Release is a tag on the repository that denotes a specific set of (documented) functionality. Right now the only Releases planned by this definition are v1.0 planned for December 2014 and v2.0 planned for December 2015. The "live" ODP git tree is not a release and those working with the tip have no guarantees of any API stability. All of this discussion relates to statements we make about tagged releases, not what happens at the tip on a day to day or month to month basis. If we choose to make a tagged release after v1.0 but before December 2015, we'll then pick a number based on the functional delta from the v1.0 base. If there's reason to tag a release in June 2015, for example, then we'll call it v1.x or v2.0 based on what's in it. If we wind up calling it v2.0 then what we tag in December 2015 will again be called either v2.x or v3.0 based on what's in it. Does that help? Bill On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org<mailto:mike.holmes@linaro.org>> wrote: Taras, Petri, please propose a patch with alternate wording. If we want to put the text in the API file that is fine with me. I think we should give it a module name though so that it becomes a highlighted section in the doc and not buried inside that files documentation. Mike On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org<mailto:taras.kondratiuk@linaro.org>> wrote: On 10/02/2014 11:12 PM, Mike Holmes wrote: On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org<mailto:taras.kondratiuk@linaro.org> <mailto:taras.kondratiuk@linaro.org<mailto:taras.kondratiuk@linaro.org>>> wrote: On 09/29/2014 09:24 PM, Mike Holmes wrote: Signed-off-by: Mike Holmes <mike.holmes@linaro.org<mailto:mike.holmes@linaro.org> <mailto:mike.holmes@linaro.org<mailto:mike.holmes@linaro.org>>> --- release.dox | 54 ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 release.dox diff --git a/release.dox b/release.dox new file mode 100644 index 0000000..53301ac --- /dev/null +++ b/release.dox @@ -0,0 +1,54 @@ +/* Copyright (c) 2014, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page release Release Management +@tableofcontents +@section release_numbering Numbering + +The API uses a three digit release number, for ODP this number refers to +- The API header definitions +- The reference implementation (linux-generic) +- The documentation +- The API test & validation suite that certifies each of the above. + +The header file odp_version.h contains helper macros for dealing with ODP versions in application code. + +@note The version refers to API source compatibility and not binary compatibility. +Every change in API version will require a recompilation, relinking will not be sufficient. + +The ODP API major.minor version will only change at well-defined release points. +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. + +@subsection major Major +The major digit is the ODP API generation. +A change to this digit indicates a break in backwards compatibility. +@note The incompatibility covers the whole ODP API, however the change may be a tiny change to an esoteric function that is not used by a given application. + +- Altering API signature +- Altering a structure other than adding optional items at the end. +- Changing the required calling sequence for APIs +- Changes to the installed structure i.e. the output from "make install" moves a file in a way that breaks compilation. +- New element to an enum that is an output from ODP + +@subsection minor Minor +The minor digit is for changes that are backwards compatible. +For example changes such as the addition of a new API. +Existing application code shall not have to change if the new API is not used. +- 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 + +@subsection sub Sub +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 +- bug fixes in implementation That is a version of API and should not be related to any implementation. + +*/ IMO having only Major number for backward incompatible changes is not enough. I assume each our release during the next year won't be backward compatible, so we will bump major number too often. What does too often mean ? The Linux major number is worthless, it only changes when Linus decides he wants a change, it means nothing. Linux is not a good example because it has different release policy. Linus doesn't set/communicate expectations on what is included in which release. But we do by saying that v1.x is kind of evaluation-ready and v2.x will be production-ready. GCC has been around since T-Rex (Cretaceous period) ate Triceratops for breakfast and they only made it to 4.x, so far is that good or is it bad ? The important thing is that you know what a change in number means not that it is a big or little number. That's an important thing why I'd like to have two numbers for backward incompatible changes. Two number gives more granularity to describe a 'size' of incompatibility. Let's say in one number case it is not clear what amount of changes need to be done to migrate from version 12 to 13 of ODP API. But in two number case I'd expect that minor version change will need only a few percent of application code touched. While major number change may cause a complete application redesign. Also I expect we will end up having LTS branches for each major release number, because developers may not want to do significant redesign of their application, but want to use some features added in new versions. -- Mike Holmes Linaro Sr Technical Manager LNG - ODP _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org<mailto:lng-odp@lists.linaro.org> http://lists.linaro.org/mailman/listinfo/lng-odp -- Mike Holmes Linaro Sr Technical Manager LNG - ODP
The discussion is independent of release timing. As a practical matter, I can't see us having the resources to do more than two releases a year anyway, especially as beginning with v1.0 these are intended to be real releases with some significant testing and documentation behind each of them. A mature project like Ubuntu only does two releases a year, and right now the OpenDaylight project does only one. On Fri, Oct 3, 2014 at 7:47 AM, Savolainen, Petri (NSN - FI/Espoo) < petri.savolainen@nsn.com> wrote: > We should release more often than once per year. A large application > cannot be ported/developed/maintained on the development branch. It’s > easier to follow multiple small steps, than e.g. port from v1.0 to v2.0 in > one big bang. > > > > -Petri > > > > > > *From:* lng-odp-bounces@lists.linaro.org [mailto: > lng-odp-bounces@lists.linaro.org] *On Behalf Of *ext Bill Fischofer > *Sent:* Friday, October 03, 2014 3:24 PM > *To:* Mike Holmes > *Cc:* lng-odp > *Subject:* Re: [lng-odp] [ARCH PATCH v3] Add release management > > > > There seems to be some continuing confusion as to what constitutes an ODP > Release. To date we've had exactly two: v0.1 released December 2013, and > v0.2 released March 2014. We also stated there would be no API > compatibility claims prior to v1.0. > > > > An ODP Release is a tag on the repository that denotes a specific set of > (documented) functionality. Right now the only Releases planned by this > definition are v1.0 planned for December 2014 and v2.0 planned for December > 2015. > > > > The "live" ODP git tree is not a release and those working with the tip > have no guarantees of any API stability. All of this discussion relates to > statements we make about tagged releases, not what happens at the tip on a > day to day or month to month basis. > > > > If we choose to make a tagged release after v1.0 but before December 2015, > we'll then pick a number based on the functional delta from the v1.0 base. > If there's reason to tag a release in June 2015, for example, then we'll > call it v1.x or v2.0 based on what's in it. If we wind up calling it v2.0 > then what we tag in December 2015 will again be called either v2.x or v3.0 > based on what's in it. > > > > Does that help? > > > > Bill > > > > On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > > Taras, Petri, please propose a patch with alternate wording. > > > > If we want to put the text in the API file that is fine with me. I think > we should give it a module name though so that it becomes a highlighted > section in the doc and not buried inside that files documentation. > > > > Mike > > > > On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org> > wrote: > > On 10/02/2014 11:12 PM, Mike Holmes wrote: > > > > On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org > <mailto:taras.kondratiuk@linaro.org>> wrote: > > On 09/29/2014 09:24 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > --- > release.dox | 54 > ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ > > > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number > refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the > above. > + > +The header file odp_version.h contains helper macros for > dealing with ODP versions in application code. > + > +@note The version refers to API source compatibility and not > binary compatibility. > +Every change in API version will require a recompilation, > relinking will not be sufficient. > + > +The ODP API major.minor version will only change at > well-defined release points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and > bug fix releases on the platform will be tagged @code > ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards > compatibility. > +@note The incompatibility covers the whole ODP API, however the > change may be a tiny change to an esoteric function that is not > used by a given application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the > end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make > install" moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new > API is not used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation > > > That is a version of API and should not be related to any > implementation. > > + > +*/ > > > IMO having only Major number for backward incompatible changes is not > enough. I assume each our release during the next year won't be > backward compatible, so we will bump major number too often. > > > What does too often mean ? > The Linux major number is worthless, it only changes when Linus decides > he wants a change, it means nothing. > > > Linux is not a good example because it has different release policy. > Linus doesn't set/communicate expectations on what is included in which > release. But we do by saying that v1.x is kind of evaluation-ready and > v2.x will be production-ready. > > GCC has been around since T-Rex (Cretaceous period) ate Triceratops > for breakfast and they only made it to 4.x, so far is that good or is > it bad ? > > The important thing is that you know what a change in number means not > that it is a big or little number. > > > That's an important thing why I'd like to have two numbers for backward > incompatible changes. Two number gives more granularity to describe a > 'size' of incompatibility. Let's say in one number case it is not clear > what amount of changes need to be done to migrate from version 12 to 13 > of ODP API. But in two number case I'd expect that minor version change > will need only a few percent of application code touched. While major > number change may cause a complete application redesign. > > Also I expect we will end up having LTS branches for each major release > number, because developers may not want to do significant redesign of > their application, but want to use some features added in new versions. > > > > > > -- > > *Mike Holmes* > > Linaro Sr Technical Manager > > LNG - ODP > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp > > >
On 3 October 2014 08:47, Savolainen, Petri (NSN - FI/Espoo) < petri.savolainen@nsn.com> wrote: > We should release more often than once per year. A large application > cannot be ported/developed/maintained on the development branch. It’s > easier to follow multiple small steps, than e.g. port from v1.0 to v2.0 in > one big bang. > Don't disagree, as long as we do agree on what is in it > -Petri > > > > *From:* lng-odp-bounces@lists.linaro.org [mailto: > lng-odp-bounces@lists.linaro.org] *On Behalf Of *ext Bill Fischofer > *Sent:* Friday, October 03, 2014 3:24 PM > *To:* Mike Holmes > *Cc:* lng-odp > *Subject:* Re: [lng-odp] [ARCH PATCH v3] Add release management > > > > There seems to be some continuing confusion as to what constitutes an ODP > Release. To date we've had exactly two: v0.1 released December 2013, and > v0.2 released March 2014. We also stated there would be no API > compatibility claims prior to v1.0. > > > > An ODP Release is a tag on the repository that denotes a specific set of > (documented) functionality. Right now the only Releases planned by this > definition are v1.0 planned for December 2014 and v2.0 planned for December > 2015. > > > > The "live" ODP git tree is not a release and those working with the tip > have no guarantees of any API stability. All of this discussion relates to > statements we make about tagged releases, not what happens at the tip on a > day to day or month to month basis. > > > > If we choose to make a tagged release after v1.0 but before December 2015, > we'll then pick a number based on the functional delta from the v1.0 base. > If there's reason to tag a release in June 2015, for example, then we'll > call it v1.x or v2.0 based on what's in it. If we wind up calling it v2.0 > then what we tag in December 2015 will again be called either v2.x or v3.0 > based on what's in it. > > > > Does that help? > > > > Bill > > > > On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > > Taras, Petri, please propose a patch with alternate wording. > > > > If we want to put the text in the API file that is fine with me. I think > we should give it a module name though so that it becomes a highlighted > section in the doc and not buried inside that files documentation. > > > > Mike > > > > On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org> > wrote: > > On 10/02/2014 11:12 PM, Mike Holmes wrote: > > > > On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org > <mailto:taras.kondratiuk@linaro.org>> wrote: > > On 09/29/2014 09:24 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > --- > release.dox | 54 > ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ > > > 1 file changed, 54 insertions(+) > create mode 100644 release.dox > > diff --git a/release.dox b/release.dox > new file mode 100644 > index 0000000..53301ac > --- /dev/null > +++ b/release.dox > @@ -0,0 +1,54 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page release Release Management > +@tableofcontents > +@section release_numbering Numbering > + > +The API uses a three digit release number, for ODP this number > refers to > +- The API header definitions > +- The reference implementation (linux-generic) > +- The documentation > +- The API test & validation suite that certifies each of the > above. > + > +The header file odp_version.h contains helper macros for > dealing with ODP versions in application code. > + > +@note The version refers to API source compatibility and not > binary compatibility. > +Every change in API version will require a recompilation, > relinking will not be sufficient. > + > +The ODP API major.minor version will only change at > well-defined release points. > +A release will be tagged @code ODP-<major>.<minor> @endcode and > bug fix releases on the platform will be tagged @code > ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. > + > +@subsection major Major > +The major digit is the ODP API generation. > +A change to this digit indicates a break in backwards > compatibility. > +@note The incompatibility covers the whole ODP API, however the > change may be a tiny change to an esoteric function that is not > used by a given application. > + > +- Altering API signature > +- Altering a structure other than adding optional items at the > end. > +- Changing the required calling sequence for APIs > +- Changes to the installed structure i.e. the output from "make > install" moves a file in a way that breaks compilation. > +- New element to an enum that is an output from ODP > + > +@subsection minor Minor > +The minor digit is for changes that are backwards compatible. > +For example changes such as the addition of a new API. > +Existing application code shall not have to change if the new > API is not used. > +- 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 > + > +@subsection sub Sub > +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 > +- bug fixes in implementation > > > That is a version of API and should not be related to any > implementation. > > + > +*/ > > > IMO having only Major number for backward incompatible changes is not > enough. I assume each our release during the next year won't be > backward compatible, so we will bump major number too often. > > > What does too often mean ? > The Linux major number is worthless, it only changes when Linus decides > he wants a change, it means nothing. > > > Linux is not a good example because it has different release policy. > Linus doesn't set/communicate expectations on what is included in which > release. But we do by saying that v1.x is kind of evaluation-ready and > v2.x will be production-ready. > > GCC has been around since T-Rex (Cretaceous period) ate Triceratops > for breakfast and they only made it to 4.x, so far is that good or is > it bad ? > > The important thing is that you know what a change in number means not > that it is a big or little number. > > > That's an important thing why I'd like to have two numbers for backward > incompatible changes. Two number gives more granularity to describe a > 'size' of incompatibility. Let's say in one number case it is not clear > what amount of changes need to be done to migrate from version 12 to 13 > of ODP API. But in two number case I'd expect that minor version change > will need only a few percent of application code touched. While major > number change may cause a complete application redesign. > > Also I expect we will end up having LTS branches for each major release > number, because developers may not want to do significant redesign of > their application, but want to use some features added in new versions. > > > > > > -- > > *Mike Holmes* > > Linaro Sr Technical Manager > > LNG - ODP > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp > > >
This is still a hot topic. Trying to summarise again. - We may release more than once a year - remembering that we need a lot test cases to qualify the release, not just the code itself - We call a planned released by their month and year AUG2015, DEC2015 etc until they happen and get a number - We Just need to decide on one or two digits meaning a break in compatibility, right now we have 3 votes for the proposed patch and 2 against. I think we would all prefer that the major only changes on each planned release, but is there any harm it changing more frequently. A change is just a reflection of the fact that at the official release point we did indeed change the API, that is the purpose of the number. It will infact follow the perfect numbering plan unless we have to make an unplanned backwards incompatible release. Note again that there can be many interim tags that are not official releases that are named DEC2015.alpha, beta etc On 3 October 2014 08:55, Mike Holmes <mike.holmes@linaro.org> wrote: > > > On 3 October 2014 08:47, Savolainen, Petri (NSN - FI/Espoo) < > petri.savolainen@nsn.com> wrote: > >> We should release more often than once per year. A large application >> cannot be ported/developed/maintained on the development branch. It’s >> easier to follow multiple small steps, than e.g. port from v1.0 to v2.0 in >> one big bang. >> > > Don't disagree, as long as we do agree on what is in it > >> -Petri >> >> >> >> *From:* lng-odp-bounces@lists.linaro.org [mailto: >> lng-odp-bounces@lists.linaro.org] *On Behalf Of *ext Bill Fischofer >> *Sent:* Friday, October 03, 2014 3:24 PM >> *To:* Mike Holmes >> *Cc:* lng-odp >> *Subject:* Re: [lng-odp] [ARCH PATCH v3] Add release management >> >> >> >> There seems to be some continuing confusion as to what constitutes an ODP >> Release. To date we've had exactly two: v0.1 released December 2013, and >> v0.2 released March 2014. We also stated there would be no API >> compatibility claims prior to v1.0. >> >> >> >> An ODP Release is a tag on the repository that denotes a specific set of >> (documented) functionality. Right now the only Releases planned by this >> definition are v1.0 planned for December 2014 and v2.0 planned for December >> 2015. >> >> >> >> The "live" ODP git tree is not a release and those working with the tip >> have no guarantees of any API stability. All of this discussion relates to >> statements we make about tagged releases, not what happens at the tip on a >> day to day or month to month basis. >> >> >> >> If we choose to make a tagged release after v1.0 but before December >> 2015, we'll then pick a number based on the functional delta from the v1.0 >> base. If there's reason to tag a release in June 2015, for example, then >> we'll call it v1.x or v2.0 based on what's in it. If we wind up calling it >> v2.0 then what we tag in December 2015 will again be called either v2.x or >> v3.0 based on what's in it. >> >> >> >> Does that help? >> >> >> >> Bill >> >> >> >> On Fri, Oct 3, 2014 at 6:34 AM, Mike Holmes <mike.holmes@linaro.org> >> wrote: >> >> Taras, Petri, please propose a patch with alternate wording. >> >> >> >> If we want to put the text in the API file that is fine with me. I think >> we should give it a module name though so that it becomes a highlighted >> section in the doc and not buried inside that files documentation. >> >> >> >> Mike >> >> >> >> On 3 October 2014 04:39, Taras Kondratiuk <taras.kondratiuk@linaro.org> >> wrote: >> >> On 10/02/2014 11:12 PM, Mike Holmes wrote: >> >> >> >> On 2 October 2014 11:55, Taras Kondratiuk <taras.kondratiuk@linaro.org >> <mailto:taras.kondratiuk@linaro.org>> wrote: >> >> On 09/29/2014 09:24 PM, Mike Holmes wrote: >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org >> <mailto:mike.holmes@linaro.org>> >> --- >> release.dox | 54 >> ++++++++++++++++++++++++++++++__++++++++++++++++++++++++ >> >> >> 1 file changed, 54 insertions(+) >> create mode 100644 release.dox >> >> diff --git a/release.dox b/release.dox >> new file mode 100644 >> index 0000000..53301ac >> --- /dev/null >> +++ b/release.dox >> @@ -0,0 +1,54 @@ >> +/* Copyright (c) 2014, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page release Release Management >> +@tableofcontents >> +@section release_numbering Numbering >> + >> +The API uses a three digit release number, for ODP this number >> refers to >> +- The API header definitions >> +- The reference implementation (linux-generic) >> +- The documentation >> +- The API test & validation suite that certifies each of the >> above. >> + >> +The header file odp_version.h contains helper macros for >> dealing with ODP versions in application code. >> + >> +@note The version refers to API source compatibility and not >> binary compatibility. >> +Every change in API version will require a recompilation, >> relinking will not be sufficient. >> + >> +The ODP API major.minor version will only change at >> well-defined release points. >> +A release will be tagged @code ODP-<major>.<minor> @endcode and >> bug fix releases on the platform will be tagged @code >> ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. >> + >> +@subsection major Major >> +The major digit is the ODP API generation. >> +A change to this digit indicates a break in backwards >> compatibility. >> +@note The incompatibility covers the whole ODP API, however the >> change may be a tiny change to an esoteric function that is not >> used by a given application. >> + >> +- Altering API signature >> +- Altering a structure other than adding optional items at the >> end. >> +- Changing the required calling sequence for APIs >> +- Changes to the installed structure i.e. the output from "make >> install" moves a file in a way that breaks compilation. >> +- New element to an enum that is an output from ODP >> + >> +@subsection minor Minor >> +The minor digit is for changes that are backwards compatible. >> +For example changes such as the addition of a new API. >> +Existing application code shall not have to change if the new >> API is not used. >> +- 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 >> + >> +@subsection sub Sub >> +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 >> +- bug fixes in implementation >> >> >> That is a version of API and should not be related to any >> implementation. >> >> + >> +*/ >> >> >> IMO having only Major number for backward incompatible changes is not >> enough. I assume each our release during the next year won't be >> backward compatible, so we will bump major number too often. >> >> >> What does too often mean ? >> The Linux major number is worthless, it only changes when Linus decides >> he wants a change, it means nothing. >> >> >> Linux is not a good example because it has different release policy. >> Linus doesn't set/communicate expectations on what is included in which >> release. But we do by saying that v1.x is kind of evaluation-ready and >> v2.x will be production-ready. >> >> GCC has been around since T-Rex (Cretaceous period) ate Triceratops >> for breakfast and they only made it to 4.x, so far is that good or is >> it bad ? >> >> The important thing is that you know what a change in number means not >> that it is a big or little number. >> >> >> That's an important thing why I'd like to have two numbers for backward >> incompatible changes. Two number gives more granularity to describe a >> 'size' of incompatibility. Let's say in one number case it is not clear >> what amount of changes need to be done to migrate from version 12 to 13 >> of ODP API. But in two number case I'd expect that minor version change >> will need only a few percent of application code touched. While major >> number change may cause a complete application redesign. >> >> Also I expect we will end up having LTS branches for each major release >> number, because developers may not want to do significant redesign of >> their application, but want to use some features added in new versions. >> >> >> >> >> >> -- >> >> *Mike Holmes* >> >> Linaro Sr Technical Manager >> >> LNG - ODP >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> >> > > > > -- > *Mike Holmes* > Linaro Sr Technical Manager > LNG - ODP >
diff --git a/release.dox b/release.dox new file mode 100644 index 0000000..53301ac --- /dev/null +++ b/release.dox @@ -0,0 +1,54 @@ +/* Copyright (c) 2014, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page release Release Management +@tableofcontents +@section release_numbering Numbering + +The API uses a three digit release number, for ODP this number refers to +- The API header definitions +- The reference implementation (linux-generic) +- The documentation +- The API test & validation suite that certifies each of the above. + +The header file odp_version.h contains helper macros for dealing with ODP versions in application code. + +@note The version refers to API source compatibility and not binary compatibility. +Every change in API version will require a recompilation, relinking will not be sufficient. + +The ODP API major.minor version will only change at well-defined release points. +A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix releases on the platform will be tagged @code ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1. + +@subsection major Major +The major digit is the ODP API generation. +A change to this digit indicates a break in backwards compatibility. +@note The incompatibility covers the whole ODP API, however the change may be a tiny change to an esoteric function that is not used by a given application. + +- Altering API signature +- Altering a structure other than adding optional items at the end. +- Changing the required calling sequence for APIs +- Changes to the installed structure i.e. the output from "make install" moves a file in a way that breaks compilation. +- New element to an enum that is an output from ODP + +@subsection minor Minor +The minor digit is for changes that are backwards compatible. +For example changes such as the addition of a new API. +Existing application code shall not have to change if the new API is not used. +- 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 + +@subsection sub Sub +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 +- bug fixes in implementation + + +*/
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 release.dox