[ARCH] Add release management

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
---
 release.dox | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 release.dox

I'd change this a bit.  The major digit indicates ODP API generation but it
does not imply backward incompatibility.  What it says is that backward
compatibility is not guaranteed for major digit changes.  Alternately, that
any changes that are not backward compatible will only appear as part of
major digit changes.

Backward incompatibility is defined as any API change that would require
application source code change.  Recompiles are considered normal and are
expected across any release change.


On Thu, Sep 25, 2014 at 4:07 PM, Mike Holmes <mike.holmes@linaro.org> wrote:

> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
> ---
>  release.dox | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
>  create mode 100644 release.dox
>
> diff --git a/release.dox b/release.dox
> new file mode 100644
> index 0000000..28d1b01
> --- /dev/null
> +++ b/release.dox
> @@ -0,0 +1,46 @@
> +/* Copyright (c) 2013, 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 suit that certifies the headers and
> documentation.
> +
> +The ODP API major.minor version will only change at well-defined release
> points.
> +A release will be tagged ODP-<major>.<minor> and bug fix releases on the
> platform will be tagged ODP-<major>.<minor>.<sub> first bug fix release sub
> = 1.
> +
> +@subsection major Major
> +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
> +
> +@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 application 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 2014-09-25 20:52, Bill Fischofer wrote:
> I'd change this a bit.  The major digit indicates ODP API generation but it
> does not imply backward incompatibility.  What it says is that backward
> compatibility is not guaranteed for major digit changes.  Alternately, that
> any changes that are not backward compatible will only appear as part of
> major digit changes.
> 
> Backward incompatibility is defined as any API change that would require
> application source code change.  Recompiles are considered normal and are
> expected across any release change.

I like Mike's proposal better because it is clearer for the end user.
For example he will know when the major version is changed he must
modify his source code and when minor version is changed he only needs
to relink his software.

Cheers,
Anders

PS. The only nit I missed during reviewing is that Copyright year must
be changed to 2014.
DS.

> 
> 
> On Thu, Sep 25, 2014 at 4:07 PM, Mike Holmes <mike.holmes@linaro.org> wrote:
> 
> > Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> > Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
> > ---
> >  release.dox | 46 ++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 46 insertions(+)
> >  create mode 100644 release.dox
> >
> > diff --git a/release.dox b/release.dox
> > new file mode 100644
> > index 0000000..28d1b01
> > --- /dev/null
> > +++ b/release.dox
> > @@ -0,0 +1,46 @@
> > +/* Copyright (c) 2013, 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 suit that certifies the headers and
> > documentation.
> > +
> > +The ODP API major.minor version will only change at well-defined release
> > points.
> > +A release will be tagged ODP-<major>.<minor> and bug fix releases on the
> > platform will be tagged ODP-<major>.<minor>.<sub> first bug fix release sub
> > = 1.
> > +
> > +@subsection major Major
> > +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
> > +
> > +@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 application 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
> >

> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp

As worded this implies that when moving between API major versions all of
the ODP APIs will be incompatible, which is clearly not the intent.
Applications MAY require source code changes when moving from one major
version to the next but this needs to be assessed on an
application-by-application basis.  For example, if v2.0 includes a backward
incompatible change to an API but a given application doesn't make use of
that API then it won't require source code changes.  It's not like we're
going to go out of our way to ensure that every API is incompatible.

On Fri, Sep 26, 2014 at 5:36 AM, Anders Roxell <anders.roxell@linaro.org>
wrote:

> On 2014-09-25 20:52, Bill Fischofer wrote:
> > I'd change this a bit.  The major digit indicates ODP API generation but
> it
> > does not imply backward incompatibility.  What it says is that backward
> > compatibility is not guaranteed for major digit changes.  Alternately,
> that
> > any changes that are not backward compatible will only appear as part of
> > major digit changes.
> >
> > Backward incompatibility is defined as any API change that would require
> > application source code change.  Recompiles are considered normal and are
> > expected across any release change.
>
> I like Mike's proposal better because it is clearer for the end user.
> For example he will know when the major version is changed he must
> modify his source code and when minor version is changed he only needs
> to relink his software.
>
> Cheers,
> Anders
>
> PS. The only nit I missed during reviewing is that Copyright year must
> be changed to 2014.
> DS.
>
> >
> >
> > On Thu, Sep 25, 2014 at 4:07 PM, Mike Holmes <mike.holmes@linaro.org>
> wrote:
> >
> > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> > > Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
> > > ---
> > >  release.dox | 46 ++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 46 insertions(+)
> > >  create mode 100644 release.dox
> > >
> > > diff --git a/release.dox b/release.dox
> > > new file mode 100644
> > > index 0000000..28d1b01
> > > --- /dev/null
> > > +++ b/release.dox
> > > @@ -0,0 +1,46 @@
> > > +/* Copyright (c) 2013, 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 suit that certifies the headers and
> > > documentation.
> > > +
> > > +The ODP API major.minor version will only change at well-defined
> release
> > > points.
> > > +A release will be tagged ODP-<major>.<minor> and bug fix releases on
> the
> > > platform will be tagged ODP-<major>.<minor>.<sub> first bug fix
> release sub
> > > = 1.
> > > +
> > > +@subsection major Major
> > > +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
> > > +
> > > +@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 application 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
> > >
>
> > _______________________________________________
> > lng-odp mailing list
> > lng-odp@lists.linaro.org
> > http://lists.linaro.org/mailman/listinfo/lng-odp
>
>

On 2014-09-26 05:45, Bill Fischofer wrote:
> As worded this implies that when moving between API major versions all of

No not all only some API will be incompatible.

> the ODP APIs will be incompatible, which is clearly not the intent.
> Applications MAY require source code changes when moving from one major
> version to the next but this needs to be assessed on an
> application-by-application basis.  For example, if v2.0 includes a backward
> incompatible change to an API but a given application doesn't make use of
> that API then it won't require source code changes.  It's not like we're
> going to go out of our way to ensure that every API is incompatible.
> 
> On Fri, Sep 26, 2014 at 5:36 AM, Anders Roxell <anders.roxell@linaro.org>
> wrote:
> 

[...]

> > > > +
> > > > +The ODP API major.minor version will only change at well-defined
> > release
> > > > points.
> > > > +A release will be tagged ODP-<major>.<minor> and bug fix releases on
> > the
> > > > platform will be tagged ODP-<major>.<minor>.<sub> first bug fix
> > release sub
> > > > = 1.
> > > > +
> > > > +@subsection major Major
> > > > +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

So you think this would be a better fit (I added "most likely"):

"It would be used generally to indicate backward incompatibility, a
change to this digit will most likely break backwards compatibility"

However, we still have to define clear criteria for when to change the
major number so that this does _not_ happen too often.

Cheers,
Anders

> > > > +- 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
> > > > +
> > > > +@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 application 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
> > > >
> >
> > > _______________________________________________
> > > lng-odp mailing list
> > > lng-odp@lists.linaro.org
> > > http://lists.linaro.org/mailman/listinfo/lng-odp
> >
> >

I think requirements / instructions are best written to be explicit and not
have soft meanings, how about being more specific and keeping the
implication that major=something is broken as far as backwards
compatibility is concerned.

Maybe clearly point out that this may only be true for a possibly esoteric
part of the API that you may not in fact use

On 26 September 2014 07:06, Anders Roxell <anders.roxell@linaro.org> wrote:

> On 2014-09-26 05:45, Bill Fischofer wrote:
> > As worded this implies that when moving between API major versions all of
>
> No not all only some API will be incompatible.
>
> > the ODP APIs will be incompatible, which is clearly not the intent.
> > Applications MAY require source code changes when moving from one major
> > version to the next but this needs to be assessed on an
> > application-by-application basis.  For example, if v2.0 includes a
> backward
> > incompatible change to an API but a given application doesn't make use of
> > that API then it won't require source code changes.  It's not like we're
> > going to go out of our way to ensure that every API is incompatible.
> >
> > On Fri, Sep 26, 2014 at 5:36 AM, Anders Roxell <anders.roxell@linaro.org
> >
> > wrote:
> >
>
> [...]
>
> > > > > +
> > > > > +The ODP API major.minor version will only change at well-defined
> > > release
> > > > > points.
> > > > > +A release will be tagged ODP-<major>.<minor> and bug fix releases
> on
> > > the
> > > > > platform will be tagged ODP-<major>.<minor>.<sub> first bug fix
> > > release sub
> > > > > = 1.
> > > > > +
> > > > > +@subsection major Major
> > > > > +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
>
> So you think this would be a better fit (I added "most likely"):
>
> "It would be used generally to indicate backward incompatibility, a
> change to this digit will most likely break backwards compatibility"
>
> However, we still have to define clear criteria for when to change the
> major number so that this does _not_ happen too often.
>
> Cheers,
> Anders
>
> > > > > +- 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
> > > > > +
> > > > > +@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 application 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
> > > > >
> > >
> > > > _______________________________________________
> > > > lng-odp mailing list
> > > > lng-odp@lists.linaro.org
> > > > http://lists.linaro.org/mailman/listinfo/lng-odp
> > >
> > >
>

Agreed.  I just want to be clear that incompatible changes are not
wholesale and will be done for specific good reasons.

On Fri, Sep 26, 2014 at 6:24 AM, Mike Holmes <mike.holmes@linaro.org> wrote:

> I think requirements / instructions are best written to be explicit and
> not have soft meanings, how about being more specific and keeping the
> implication that major=something is broken as far as backwards
> compatibility is concerned.
>
> Maybe clearly point out that this may only be true for a possibly esoteric
> part of the API that you may not in fact use
>
> On 26 September 2014 07:06, Anders Roxell <anders.roxell@linaro.org>
> wrote:
>
>> On 2014-09-26 05:45, Bill Fischofer wrote:
>> > As worded this implies that when moving between API major versions all
>> of
>>
>> No not all only some API will be incompatible.
>>
>> > the ODP APIs will be incompatible, which is clearly not the intent.
>> > Applications MAY require source code changes when moving from one major
>> > version to the next but this needs to be assessed on an
>> > application-by-application basis.  For example, if v2.0 includes a
>> backward
>> > incompatible change to an API but a given application doesn't make use
>> of
>> > that API then it won't require source code changes.  It's not like we're
>> > going to go out of our way to ensure that every API is incompatible.
>> >
>> > On Fri, Sep 26, 2014 at 5:36 AM, Anders Roxell <
>> anders.roxell@linaro.org>
>> > wrote:
>> >
>>
>> [...]
>>
>> > > > > +
>> > > > > +The ODP API major.minor version will only change at well-defined
>> > > release
>> > > > > points.
>> > > > > +A release will be tagged ODP-<major>.<minor> and bug fix
>> releases on
>> > > the
>> > > > > platform will be tagged ODP-<major>.<minor>.<sub> first bug fix
>> > > release sub
>> > > > > = 1.
>> > > > > +
>> > > > > +@subsection major Major
>> > > > > +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
>>
>> So you think this would be a better fit (I added "most likely"):
>>
>> "It would be used generally to indicate backward incompatibility, a
>> change to this digit will most likely break backwards compatibility"
>>
>> However, we still have to define clear criteria for when to change the
>> major number so that this does _not_ happen too often.
>>
>> Cheers,
>> Anders
>>
>> > > > > +- 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
>> > > > > +
>> > > > > +@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 application 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
>> > > > >
>> > >
>> > > > _______________________________________________
>> > > > lng-odp mailing list
>> > > > lng-odp@lists.linaro.org
>> > > > http://lists.linaro.org/mailman/listinfo/lng-odp
>> > >
>> > >
>>
>
>
>
> --
> *Mike Holmes*
> Linaro Technical Manager / Lead
> LNG - ODP
>