From: ext Maxim Uvarov [mailto:[email protected]] Sent: Monday, October 27, 2014 2:17 PM To: Savolainen, Petri (NSN - FI/Espoo) Cc: [email protected] Subject: Re: [lng-odp] [PATCHv2] odp_version.h: Update version number On 27 October 2014 14:55, Savolainen, Petri (NSN - FI/Espoo) <[email protected]> wrote: > -----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. The latest patch is v3. We with Mike discussed versions with 4 digits. So I think it should be documented somewhere. Let's discuss that one more time. We definitely need to be synchronized here. Can you send a link into that thread. I didn’t find it from the mailing list. > > 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. odp.git is API and linux-generic implementation, right? Even if function is not implemented there has to be place holder. So I think we are speaking about the same thing here. > > 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. that is why we need #define MAJOR for that. > > 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? Yes. That is requirement from LNG members. They need to see progress. And want to see numbers increasing. We can not avoid that. Progress == working code, not rolling version numbers without content. API version must not be touched if API has not changed. The implementation versioning / repo tagging must be handled other way than rolling API version number. API and implementation version numbers have different goals and must not be merged. > > 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. Yes, it's implementation only. But because odp.git has both API and linux-generic implementation we need that number somewhere. We’ll update API version number when API changes, and implementation version number when implementation changes. For example, this change in linux-generic implementation would not roll API version number at all. before: /** * ODP buffer */ typedef uint32_t odp_buffer_t; after: /** * ODP buffer */ typedef void* odp_buffer_t; -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
