[ARCH,v3] Add release management

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
---
v3:
Spelling

V2:
Add a note to the Major section to highlight that although the API is now backwards incompatible, the change may be inconsequential to a given application.
Fix copyright date.

 release.dox | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 release.dox

Ignore this, I missed Santosh's patch which adds another exit.

On 26 September 2014 12:04, Mike Holmes <mike.holmes@linaro.org> wrote:

> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
> ---
> v3:
> Spelling
>
> V2:
> Add a note to the Major section to highlight that although the API is now
> backwards incompatible, the change may be inconsequential to a given
> application.
> Fix copyright date.
>
>  release.dox | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
>  create mode 100644 release.dox
>
> diff --git a/release.dox b/release.dox
> new file mode 100644
> index 0000000..7caa662
> --- /dev/null
> +++ b/release.dox
> @@ -0,0 +1,48 @@
> +/* 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 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.
> +A change to this digit will break 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
> +- 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 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
>
>

On Fri, Sep 26, 2014 at 05:04:11PM +0100, Mike Holmes wrote:
> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
> ---
> v3:
> Spelling
> 
> V2:
> Add a note to the Major section to highlight that although the API is now backwards incompatible, the change may be inconsequential to a given application.
> Fix copyright date.
> 
>  release.dox | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
>  create mode 100644 release.dox
> 
> diff --git a/release.dox b/release.dox
> new file mode 100644
> index 0000000..7caa662
> --- /dev/null
> +++ b/release.dox
> @@ -0,0 +1,48 @@
> +/* 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 suit that certifies the headers and documentation.

s/suit/suite

It verifies the implementation too, so maybe "each of the above".

> +
> +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.
> +A change to this digit will break backwards compatibility.

The change in version number isn't what causes the break, how about
"indicates a break in" rather than "will break".

> +@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 to the end)

> +- Changing the required calling sequence for APIs
> +- Changes to the installed structure

Does this mean the location of installed components in the file system?
I don't think that should effect the API version, it's just a packaging
issue. Even if some of the headers are moved/renamed, the application
source's view of things shouldn't change as it'll only be including odp.h

> +- 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)a
> +- Optimize the implementation
> +- Documentation updates
> +- bug fixes in implementation
> +
> +*/
> -- 
> 1.9.1

It would also be worth pointing out here that there are related macros
in odp_version.h

It's also worth noting that this is referring to API source compatibility
not binary compatibility, for every change in API version an application
needs to be recompiled, relinking is not sufficient.

On 29 September 2014 07:38, Stuart Haslam <stuart.haslam@arm.com> wrote:

> On Fri, Sep 26, 2014 at 05:04:11PM +0100, Mike Holmes wrote:
> > Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> > Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
> > ---
> > v3:
> > Spelling
> >
> > V2:
> > Add a note to the Major section to highlight that although the API is
> now backwards incompatible, the change may be inconsequential to a given
> application.
> > Fix copyright date.
> >
> >  release.dox | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 48 insertions(+)
> >  create mode 100644 release.dox
> >
> > diff --git a/release.dox b/release.dox
> > new file mode 100644
> > index 0000000..7caa662
> > --- /dev/null
> > +++ b/release.dox
> > @@ -0,0 +1,48 @@
> > +/* 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 suit that certifies the headers and
> documentation.
>
> s/suit/suite
>
> It verifies the implementation too, so maybe "each of the above".
>
> > +
> > +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.
> > +A change to this digit will break backwards compatibility.
>
> The change in version number isn't what causes the break, how about
> "indicates a break in" rather than "will break".
>
> > +@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 to the end)
>
> > +- Changing the required calling sequence for APIs
> > +- Changes to the installed structure
>
> Does this mean the location of installed components in the file system?
> I don't think that should effect the API version, it's just a packaging
> issue. Even if some of the headers are moved/renamed, the application
> source's view of things shouldn't change as it'll only be including odp.h
>
The thought was that if we install  <prefix>/install/helper_one.h and
change it to <prefix>/install/helpers/hellper_one.h

>
> > +- 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)a
> > +- Optimize the implementation
> > +- Documentation updates
> > +- bug fixes in implementation
> > +
> > +*/
> > --
> > 1.9.1
>
> It would also be worth pointing out here that there are related macros
> in odp_version.h
>
> It's also worth noting that this is referring to API source compatibility
> not binary compatibility, for every change in API version an application
> needs to be recompiled, relinking is not sufficient.
>


Thanks Stuart - I incorporated all your comments and will post again.

>
> --
> Stuart.
>
>