| Message ID | 1470760002-19100-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
On 9 August 2016 at 12:26, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Add additional detail and examples to the description of the release > naming scheme used by ODP, detailing the expected impact to ODP > applications and/or other ODP implementations for each change. > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > doc/process-guide/release-guide.adoc | 76 +++++++++++++++++++++++++++++- > ------ > 1 file changed, 62 insertions(+), 14 deletions(-) > > diff --git a/doc/process-guide/release-guide.adoc > b/doc/process-guide/release-guide.adoc > index 8816c03..83d0ca1 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -116,28 +116,76 @@ atomically as possible > * the maintainer tags the master branch > > == Releases == > -All releases are from master. > +All releases are from master. Recall that ODP consists of three separate > +components: > This should be clarified by saying the release comes from a tag in master. In Monarch_lts we used this hash of 19771^Cc229f3db775a97c27e09c2dc063497c4 which was not tagged Head monarch = 9c8ab9126181e5457f5711075b97ca9ec9a20fc8 Head Master = e072ea084a27df729d1b94c0bec2d45fb1e4d26f git merge-base e072ea084a27df729d1b94c0bec2d45fb1e4d26f 9c8ab9126181e5457f5711075b97ca9ec9a20fc8 git show 19771^Cc229f3db775a97c27e09c2dc063497c4 We must also state that git and the change log is tagged with the four digits, we have to do that for the tools to work and to allow others to know if they care about the tagged release point without reading everything. > > -They are tagged in the repository using the format > -v<Generation>.<Major>.<Minor>.<Impl> > -There are three release types with differing frequencies and impact to the > -applications. > +* An API Specification > +* Multiple independently owned and maintained _implementations_ of the > ODP API > +* A Validation Test Suite that tests implementation conformance to the > ODP API > + > +Included with the main ODP git repository is the `odp-linux` reference > +implementation of the ODP API, and it also has an associated service > stream > +that is independent of all other ODP implementations. This means that the > ODP > +release naming conventions address the needs of all three of these > components, > +which is accomplished via a multi-level structure using the format: > + > +*v<Generation>.<Major>.<Minor>.<Point>* > + > +The first three of these digits represent the ODP API level, and these > reflect > +three types of API changes with differing frequencies and impact to > +applications and other ODP implementations. A fourth digit is used to > reflect > +changes to other items included within the ODP git repository. In > addition, > +each individual ODP implementation will have its own service stream > +identifier that is defined using whatever conventions meet its needs. > > === Generation releases === > A generation release indicates a major completion of work, and a possible > -change in direction for the API. Same as for Major release plus they are > -defined by the Steering committee. > +change in direction for the API. Generation release changes are approved > by the > +LNG Steering Committee, which is the governing body for ODP. > > === Major releases === > -Major (API) releases are scheduled to be about once a > -quarter, but when there is significant progress made they may be more > frequent. > +Major (API) releases are used when new APIs or capabilities are > introduced or > +changes are made to existing APIs that are not backwards-compatible. Major > +release changes thus potentially affect ODP applications as well as > +implementations. > + > +=== Minor releases === > +Minor (API) releases are used when new APIs or capabilities are > introduced or > +changes are made to existing APIs in a backwards-compatible manner. > Examples > +of these might be wording changes in API documentation, or introducing new > +APIs that are orthogonal to the existing set of APIs and hence have no > impact > +on existing applications that do not make use of them. Minor release > changes > +should therefore have no impact on existing ODP applications but will have > +impact for ODP implementations that need to support these API additions > and > +changes. > + > +NOTE: The first three digits of the release name are the API version > returned > +by the `odp_version_api_str()` API. > > === Point releases === > -General bug fixes and other non API altering changes are gathered and a > release > -made every month if sufficient change has accumulated. > - > -=== Implementation (Impl) === > -Platform specific free form text relating to the version. > +General bug fixes and other non API altering changes are gathered and a > +release made every month if sufficient change has accumulated. Examples > of a > +point release would be additional documentation, extensions or > corrections to > +the validation test suite, additions or corrections to helpers, example > +programs, etc. No API changes are permitted in a point release, so ODP > +applications are not impacted. Other ODP implementations _may_ be > impacted > +if, for example, a bug is fixed in a validation test that results in a > latent > +bug in other implementations being exposed. > + > +=== Implementation Service Strings === > +Beyond the four-digit release name, platform specific free form text is > used > +to capture the service level of each ODP implementation. This field is > for the > +sole use of implementations to represent their individual service > streams. Its > +format may vary between implementations. For example, the `odp-linux` > +reference implementation uses a simple incrementing digit (0, 1, 2, > +etc.). Other implementations may use `Build xxxx` or something similar. > +Changes in this designator have no impact on and may be ignored by other > ODP > +implementations. The only changes that ODP applications should see is > +corrected functional or performance behavior when running on that > specific ODP > +implementation. > + > +NOTE: The full four-digit release name plus implementation service string > is > +returned by the `odp_version_impl_name()` API. > > == Deprecating part of the API > Deleting or changing the published API follows the normal > <<anchor-1,process>>, with the following additional rules: > -- > 2.7.4 > > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collaborative, the rest follows"
On Tuesday, August 9, 2016, Mike Holmes <mike.holmes@linaro.org> wrote: > > > On 9 August 2016 at 12:26, Bill Fischofer <bill.fischofer@linaro.org > <javascript:_e(%7B%7D,'cvml','bill.fischofer@linaro.org');>> wrote: > >> Add additional detail and examples to the description of the release >> naming scheme used by ODP, detailing the expected impact to ODP >> applications and/or other ODP implementations for each change. >> >> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org >> <javascript:_e(%7B%7D,'cvml','bill.fischofer@linaro.org');>> >> --- >> doc/process-guide/release-guide.adoc | 76 +++++++++++++++++++++++++++++- >> ------ >> 1 file changed, 62 insertions(+), 14 deletions(-) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index 8816c03..83d0ca1 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -116,28 +116,76 @@ atomically as possible >> * the maintainer tags the master branch >> >> == Releases == >> -All releases are from master. >> +All releases are from master. Recall that ODP consists of three separate >> +components: >> > > This should be clarified by saying the release comes from a tag in master. > > In Monarch_lts we used this hash of 19771^Cc229f3db775a97c27e09c2dc063497c4 which was > not tagged > > Head monarch = 9c8ab9126181e5457f5711075b97ca9ec9a20fc8 > Head Master = e072ea084a27df729d1b94c0bec2d45fb1e4d26f > git merge-base e072ea084a27df729d1b94c0bec2d45fb1e4d26f > 9c8ab9126181e5457f5711075b97ca9ec9a20fc8 > git show 19771^Cc229f3db775a97c27e09c2dc063497c4 > > We must also state that git and the change log is tagged with the > four digits, we have to do that for the tools to work and to allow > others to know if they care about the tagged release point without reading > everything. > Ok. I'll sent a v3 with these amplifications and additions. > > >> >> -They are tagged in the repository using the format >> -v<Generation>.<Major>.<Minor>.<Impl> >> -There are three release types with differing frequencies and impact to >> the >> -applications. >> +* An API Specification >> +* Multiple independently owned and maintained _implementations_ of the >> ODP API >> +* A Validation Test Suite that tests implementation conformance to the >> ODP API >> + >> +Included with the main ODP git repository is the `odp-linux` reference >> +implementation of the ODP API, and it also has an associated service >> stream >> +that is independent of all other ODP implementations. This means that >> the ODP >> +release naming conventions address the needs of all three of these >> components, >> +which is accomplished via a multi-level structure using the format: >> + >> +*v<Generation>.<Major>.<Minor>.<Point>* >> + >> +The first three of these digits represent the ODP API level, and these >> reflect >> +three types of API changes with differing frequencies and impact to >> +applications and other ODP implementations. A fourth digit is used to >> reflect >> +changes to other items included within the ODP git repository. In >> addition, >> +each individual ODP implementation will have its own service stream >> +identifier that is defined using whatever conventions meet its needs. >> >> === Generation releases === >> A generation release indicates a major completion of work, and a possible >> -change in direction for the API. Same as for Major release plus they are >> -defined by the Steering committee. >> +change in direction for the API. Generation release changes are approved >> by the >> +LNG Steering Committee, which is the governing body for ODP. >> >> === Major releases === >> -Major (API) releases are scheduled to be about once a >> -quarter, but when there is significant progress made they may be more >> frequent. >> +Major (API) releases are used when new APIs or capabilities are >> introduced or >> +changes are made to existing APIs that are not backwards-compatible. >> Major >> +release changes thus potentially affect ODP applications as well as >> +implementations. >> + >> +=== Minor releases === >> +Minor (API) releases are used when new APIs or capabilities are >> introduced or >> +changes are made to existing APIs in a backwards-compatible manner. >> Examples >> +of these might be wording changes in API documentation, or introducing >> new >> +APIs that are orthogonal to the existing set of APIs and hence have no >> impact >> +on existing applications that do not make use of them. Minor release >> changes >> +should therefore have no impact on existing ODP applications but will >> have >> +impact for ODP implementations that need to support these API additions >> and >> +changes. >> + >> +NOTE: The first three digits of the release name are the API version >> returned >> +by the `odp_version_api_str()` API. >> >> === Point releases === >> -General bug fixes and other non API altering changes are gathered and a >> release >> -made every month if sufficient change has accumulated. >> - >> -=== Implementation (Impl) === >> -Platform specific free form text relating to the version. >> +General bug fixes and other non API altering changes are gathered and a >> +release made every month if sufficient change has accumulated. Examples >> of a >> +point release would be additional documentation, extensions or >> corrections to >> +the validation test suite, additions or corrections to helpers, example >> +programs, etc. No API changes are permitted in a point release, so ODP >> +applications are not impacted. Other ODP implementations _may_ be >> impacted >> +if, for example, a bug is fixed in a validation test that results in a >> latent >> +bug in other implementations being exposed. >> + >> +=== Implementation Service Strings === >> +Beyond the four-digit release name, platform specific free form text is >> used >> +to capture the service level of each ODP implementation. This field is >> for the >> +sole use of implementations to represent their individual service >> streams. Its >> +format may vary between implementations. For example, the `odp-linux` >> +reference implementation uses a simple incrementing digit (0, 1, 2, >> +etc.). Other implementations may use `Build xxxx` or something similar. >> +Changes in this designator have no impact on and may be ignored by other >> ODP >> +implementations. The only changes that ODP applications should see is >> +corrected functional or performance behavior when running on that >> specific ODP >> +implementation. >> + >> +NOTE: The full four-digit release name plus implementation service >> string is >> +returned by the `odp_version_impl_name()` API. >> >> == Deprecating part of the API >> Deleting or changing the published API follows the normal >> <<anchor-1,process>>, with the following additional rules: >> -- >> 2.7.4 >> >> > > > -- > Mike Holmes > Technical Manager - Linaro Networking Group > Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs > "Work should be fun and collaborative, the rest follows" > > >
diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc index 8816c03..83d0ca1 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -116,28 +116,76 @@ atomically as possible * the maintainer tags the master branch == Releases == -All releases are from master. +All releases are from master. Recall that ODP consists of three separate +components: -They are tagged in the repository using the format -v<Generation>.<Major>.<Minor>.<Impl> -There are three release types with differing frequencies and impact to the -applications. +* An API Specification +* Multiple independently owned and maintained _implementations_ of the ODP API +* A Validation Test Suite that tests implementation conformance to the ODP API + +Included with the main ODP git repository is the `odp-linux` reference +implementation of the ODP API, and it also has an associated service stream +that is independent of all other ODP implementations. This means that the ODP +release naming conventions address the needs of all three of these components, +which is accomplished via a multi-level structure using the format: + +*v<Generation>.<Major>.<Minor>.<Point>* + +The first three of these digits represent the ODP API level, and these reflect +three types of API changes with differing frequencies and impact to +applications and other ODP implementations. A fourth digit is used to reflect +changes to other items included within the ODP git repository. In addition, +each individual ODP implementation will have its own service stream +identifier that is defined using whatever conventions meet its needs. === Generation releases === A generation release indicates a major completion of work, and a possible -change in direction for the API. Same as for Major release plus they are -defined by the Steering committee. +change in direction for the API. Generation release changes are approved by the +LNG Steering Committee, which is the governing body for ODP. === Major releases === -Major (API) releases are scheduled to be about once a -quarter, but when there is significant progress made they may be more frequent. +Major (API) releases are used when new APIs or capabilities are introduced or +changes are made to existing APIs that are not backwards-compatible. Major +release changes thus potentially affect ODP applications as well as +implementations. + +=== Minor releases === +Minor (API) releases are used when new APIs or capabilities are introduced or +changes are made to existing APIs in a backwards-compatible manner. Examples +of these might be wording changes in API documentation, or introducing new +APIs that are orthogonal to the existing set of APIs and hence have no impact +on existing applications that do not make use of them. Minor release changes +should therefore have no impact on existing ODP applications but will have +impact for ODP implementations that need to support these API additions and +changes. + +NOTE: The first three digits of the release name are the API version returned +by the `odp_version_api_str()` API. === Point releases === -General bug fixes and other non API altering changes are gathered and a release -made every month if sufficient change has accumulated. - -=== Implementation (Impl) === -Platform specific free form text relating to the version. +General bug fixes and other non API altering changes are gathered and a +release made every month if sufficient change has accumulated. Examples of a +point release would be additional documentation, extensions or corrections to +the validation test suite, additions or corrections to helpers, example +programs, etc. No API changes are permitted in a point release, so ODP +applications are not impacted. Other ODP implementations _may_ be impacted +if, for example, a bug is fixed in a validation test that results in a latent +bug in other implementations being exposed. + +=== Implementation Service Strings === +Beyond the four-digit release name, platform specific free form text is used +to capture the service level of each ODP implementation. This field is for the +sole use of implementations to represent their individual service streams. Its +format may vary between implementations. For example, the `odp-linux` +reference implementation uses a simple incrementing digit (0, 1, 2, +etc.). Other implementations may use `Build xxxx` or something similar. +Changes in this designator have no impact on and may be ignored by other ODP +implementations. The only changes that ODP applications should see is +corrected functional or performance behavior when running on that specific ODP +implementation. + +NOTE: The full four-digit release name plus implementation service string is +returned by the `odp_version_impl_name()` API. == Deprecating part of the API Deleting or changing the published API follows the normal <<anchor-1,process>>, with the following additional rules:
Add additional detail and examples to the description of the release naming scheme used by ODP, detailing the expected impact to ODP applications and/or other ODP implementations for each change. Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- doc/process-guide/release-guide.adoc | 76 +++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 14 deletions(-) -- 2.7.4