> -----Original Message----- > From: ext Maxim Uvarov [mailto:[email protected]] > Sent: Monday, October 27, 2014 11:07 AM > To: Savolainen, Petri (NSN - FI/Espoo); [email protected] > Subject: Re: [lng-odp] [PATCHv2] odp_version.h: Update version number > > On 10/27/2014 11:59 AM, Savolainen, Petri (NSN - FI/Espoo) wrote: > > Hi, > > > > I thought we agreed two weeks ago that API version number is three > digits: generation.major.minor. Have that now been changed to 4 digits? > Why? Or are you taking about implementation versioning? > > I think it was discussion after which Mike sent patch for versions to > ARCH doc and after that patch to linux-generic implementation. I think > you had to complain in that case, not now.
The joy of double documenting... If we are going to have only single review round, that must be the code - not some text in arch doc. Do you mean this patch from last Wednesday? [lng-odp] [PATCH ARCH 1/2] Add release management: +@page release Release Management +The odp.git repo contains the API which is of primary concern when addressing the release numbering, the linux-generic implementation is not the focus of the release. + +@section release_numbering Release Numbering (ODP-<generation>.<major>.<minor>) + +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. It talks about 3 digits, not 4 digits. The text is pretty OK, also don't recall any objections/discussion on the patch. > > Versions have 4 digits for reason which Mike described in patch and I > wrote some examples of versions (not sure if it's really clear). > > Any way we need to solve that asap so I will set up new versions tag > today. > > > Each vendor can decide how they version their implementation. > No. Idea is to make portable applications. #ifdef for version should > match linux-generic and vendor implementations at the same time. So > vendor just takes linux-generic release tag and does his own > implementation for specific version of linux-generic code tag. Application is interested in the API version number, not implementation version number. API version numbering cannot be based on linux-generic implementation. For example, linux-generic may have missing features or bugs, but API spec and other implementations may be OK. > > Application is interested in the API version number. A match in > generation.major would tell that two versions are backward compatible. So, > third digit would be incremented for backward compatible changes. A bug > fix in API may be backward compatible or not, depends on the bug. I think > it would be decided case by case which digit is increment on a bug fix > (e.g. a typo in documentation that gives wrong contract to the application > but should have been understood as a typo from the context is a minor > digit increment, etc). > > I will try to explain one more time what are the numbers. Might be it > will helpful: > > A.B.C.D > > A- generation, like odp v1.0.0.0 and v2.0.0.0 - huge code rework, big > changes in docs, architecture and etc. Usually cycle is 1 year or more. > defined as: ODP_VERSION_API_GENERATION > > B - major number - API change. Incremental change in linux generic for > backward compatibility patches. I.e. if application requires new API > this number should be increased. > defined as: ODP_VERSION_API_MAJOR These changes can be (and often are) backward incompatible. > > C - minor, increment this value each 2 weeks if applications API was not > changes. > no need special define for that because API was not change, application > remain the same. What? Increment API version number, even when API is not changed? > > D - sub value. That is very special case. > We need some value to be increased in post release branch, while main > development will go in main branch. Because we change first 3 changes in > main branch we can not touch them. So there is 4 digits. Any required > backports will not brake api. Apps for released version must be the same > for all platforms. So there will be changes which do not break api. > no need special define for that because API was not change, application > remain the same. > D is for implementation versioning, right? API version is not the same thing as linux-generic implementation tag/version. -Petri > So my point is to take Mikes patch and remove defines fro C and D from it. > > Objections? > > Maxim. > > > > > > -Petri > > > > > >> -----Original Message----- > >> From: [email protected] [mailto:lng-odp- > >> [email protected]] On Behalf Of ext Maxim Uvarov > >> Sent: Friday, October 24, 2014 6:58 PM > >> To: [email protected] > >> Subject: Re: [lng-odp] [PATCHv2] odp_version.h: Update version number > >> > >> Sub version is used for post release bug fixing. > >> > >> I.e. now we go with: > >> > >> v0.3.0.0 > >> next (no api change) > >> v0.3.1.0 > >> next (no api change) > >> v0.3.2.0 > >> > >> next (api change) > >> v0.4.0.0 > >> next (no api change) > >> v0.4.1.0 > >> > >> When v1.0.0.0 released, we will create branch, and apply only critical > >> updates. I.e it will: > >> v1.0.0.1 > >> next (no api change) > >> v1.0.0.2 > >> next (no api change) > >> v1.0.0.3 > >> > >> Non-linux-generic implementations just follow linux-generic tags: > >> v0.3.0.0 -> ks2v0.3.0.0 (ks2 code corresponding to lg tag). > >> v1.0.0.3 -> dpdkv1.0.0.3 (dpdk version corresponding to lg tag). > >> > >> Now back to your question. For apps it is important to have numbers > only > >> for versions which do break api. I.e. major and generation. And they > are > >> very transparent > >> to minor and sub. > >> > >> I also agree to not include sub and minor to define and keep it only in > >> tags. In that case we > >> will not update version each week. Less commits for versions is better > :) > >> > >> > >> Maxim. > >> > >> > >> On 10/24/2014 11:31 AM, Savolainen, Petri (NSN - FI/Espoo) wrote: > >>>> -----Original Message----- > >>>> From: [email protected] [mailto:lng-odp- > >>>> [email protected]] On Behalf Of ext Mike Holmes > >>>> Sent: Thursday, October 23, 2014 10:30 PM > >>>> To: [email protected] > >>>> Subject: [lng-odp] [PATCHv2] odp_version.h: Update version number > >>>> > >>>> Update version numnering to the ratified format. > >>>> Update the number for the point release. > >>>> > >>>> Signed-off-by: Mike Holmes <[email protected]> > >>>> --- > >>>> configure.ac | 2 +- > >>>> platform/linux-generic/include/api/odp_version.h | 28 > >> ++++++++++++++++--- > >>>> ----- > >>>> 2 files changed, 20 insertions(+), 10 deletions(-) > >>>> > >>>> diff --git a/configure.ac b/configure.ac > >>>> index aa94034..cc92013 100644 > >>>> --- a/configure.ac > >>>> +++ b/configure.ac > >>>> @@ -1,5 +1,5 @@ > >>>> AC_PREREQ([2.5]) > >>>> -AC_INIT([OpenDataPlane], [0.2], [[email protected]]) > >>>> +AC_INIT([OpenDataPlane], [0.3.0.0], [[email protected]]) > >>>> AM_INIT_AUTOMAKE([subdir-objects]) > >>>> AC_CONFIG_SRCDIR([helper/config.h.in]) > >>>> AM_CONFIG_HEADER([helper/config.h]) > >>>> diff --git a/platform/linux-generic/include/api/odp_version.h > >>>> b/platform/linux-generic/include/api/odp_version.h > >>>> index 3a75201..5b90e32 100644 > >>>> --- a/platform/linux-generic/include/api/odp_version.h > >>>> +++ b/platform/linux-generic/include/api/odp_version.h > >>>> @@ -23,29 +23,38 @@ extern "C" { > >>>> */ > >>>> > >>>> /** > >>>> - * ODP API main version > >>>> + * ODP API generation version > >>>> + * > >>>> + * Introduction of major new features or changes that make > >>>> + * very significatant changes to the API. APIs with different > >>>> + * versions are likely not backward compatible. > >>>> + */ > >>>> +#define ODP_VERSION_API_GENERATION 0 > >>>> + > >>>> +/** > >>>> + * ODP API major version > >>>> * > >>>> * Introduction of major new features or changes. APIs with > different > >>>> major > >>>> * versions are likely not backward compatible. > >>>> */ > >>>> -#define ODP_VERSION_API_MAIN 0 > >>>> +#define ODP_VERSION_API_MAJOR 3 > >>>> > >>>> /** > >>>> - * ODP API sub version > >>>> + * ODP API minor version > >>>> * > >>>> * Introduction of additional features or minor changes. APIs with > >> common > >>>> * major version and different sub versions may be backward > >> compatible > >>>> (if only > >>>> * additions). > >>> You need to update the comment text also, e.g.: > >>> Minor version is incremented when introducing backward compatible > >> changes to the API. API with common generation and major version, but > with > >> different minor version are backward compatible. > >>> > >>>> */ > >>>> -#define ODP_VERSION_API_SUB 0 > >>>> +#define ODP_VERSION_API_MINOR 0 > >>>> > >>>> /** > >>>> - * ODP API bug correction version > >>>> + * ODP API sub correction version > >>> Sub _correction_ version? > >>> > >>>> * > >>>> * Bug corrections to the API files. APIs with the same major and > sub > >>>> * versions, but different bug correction versions are backward > >>>> compatible. > >>>> */ > >>> Usage of sub version? Generation.major.minor should define the API > >> version. Sub version is used only for implementation or test cases? > How? > >>> > >>>> -#define ODP_VERSION_API_BUG 1 > >>>> +#define ODP_VERSION_API_SUB 0 > >>>> > >>>> > >>>> /** @internal Version string expand */ > >>>> @@ -56,9 +65,10 @@ extern "C" { > >>>> > >>>> /** @internal API version string */ > >>>> #define ODP_VERSION_API_STR \ > >>>> -ODP_VERSION_TO_STR(ODP_VERSION_API_MAIN) "."\ > >>>> -ODP_VERSION_TO_STR(ODP_VERSION_API_SUB) "."\ > >>>> -ODP_VERSION_TO_STR(ODP_VERSION_API_BUG) > >>>> +ODP_VERSION_TO_STR(ODP_VERSION_API_GENERATION) "."\ > >>>> +ODP_VERSION_TO_STR(ODP_VERSION_API_MAJOR) "."\ > >>>> +ODP_VERSION_TO_STR(ODP_VERSION_API_MINOR) "."\ > >>>> +ODP_VERSION_TO_STR(ODP_VERSION_API_SUB) > >>> API version string should include only generation.major.minor. > >>> > >>> Some other e.g. implementation version string could be then > >> generation.major.minor-sub? > >>> > >>> -Petri > >>> > >>> > >>> _______________________________________________ > >>> lng-odp mailing list > >>> [email protected] > >>> http://lists.linaro.org/mailman/listinfo/lng-odp > >> > >> _______________________________________________ > >> lng-odp mailing list > >> [email protected] > >> http://lists.linaro.org/mailman/listinfo/lng-odp _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
