| Message ID | 1470667920-1839-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
Looks good, one comment below On 8 August 2016 at 10:52, 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 | 51 ++++++++++++++++++++++++++++-- > ------ > 1 file changed, 40 insertions(+), 11 deletions(-) > > diff --git a/doc/process-guide/release-guide.adoc > b/doc/process-guide/release-guide.adoc > index 8816c03..6ee798d 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -116,28 +116,57 @@ 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: > + > +* 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>.<Impl>* > > -They are tagged in the repository using the format > The above sentence is important, early on there was debate that was settled by specifying that we always use the four digits so that users can immediately tell the severity of change if syncing to that tag. To make a tools use of the data simpler we said it would always be specified in the repo using the full four digits. > -v<Generation>.<Major>.<Minor>.<Impl> > There are three release types with differing frequencies and impact to the > -applications. > +applications and other ODP implementations. The fourth is simply used to > +designate the service stream associated with an individual ODP > implementation. > > === 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. These changes may not be > +backwards-compatible. Major release changes thus potentially affect ODP > +applications as well as implementations. > > === Point releases === > -General bug fixes and other non API altering changes are gathered and a > release > -made every month if sufficient change has accumulated. > +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 typographic corrections to API header file > +documentation, other additional documentation, extensions or corrections > to > +the validation test suite, additions or corrections to 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 (Impl) === > -Platform specific free form text relating to the version. > +Platform specific free form text relating to the version. 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. > > == 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 Mon, Aug 8, 2016 at 10:53 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Looks good, one comment below > > On 8 August 2016 at 10:52, 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 | 51 ++++++++++++++++++++++++++++-- >> ------ >> 1 file changed, 40 insertions(+), 11 deletions(-) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index 8816c03..6ee798d 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -116,28 +116,57 @@ 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: >> + >> +* 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>.<Impl>* >> >> -They are tagged in the repository using the format >> > > The above sentence is important, early on there was debate that was > settled by specifying that we always use the four digits so that users can > immediately tell the severity of change if syncing to that tag. > To make a tools use of the data simpler we said it would always be > specified in the repo using the full four digits. > I think I point this out in the discussion of the fourth level name <Impl> below. odp-linux (which is the implementation that is shipped with the odp git repo, uses digits for the fourth level name. But other implementations are free to use whatever is consistent with their own service strategy preferences. > > >> -v<Generation>.<Major>.<Minor>.<Impl> >> There are three release types with differing frequencies and impact to >> the >> -applications. >> +applications and other ODP implementations. The fourth is simply used to >> +designate the service stream associated with an individual ODP >> implementation. >> >> === 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. These changes may not be >> +backwards-compatible. Major release changes thus potentially affect ODP >> +applications as well as implementations. >> >> === Point releases === >> -General bug fixes and other non API altering changes are gathered and a >> release >> -made every month if sufficient change has accumulated. >> +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 typographic corrections to API header file >> +documentation, other additional documentation, extensions or corrections >> to >> +the validation test suite, additions or corrections to 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 (Impl) === >> -Platform specific free form text relating to the version. >> +Platform specific free form text relating to the version. 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. >> >> == 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..6ee798d 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -116,28 +116,57 @@ 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: + +* 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>.<Impl>* -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. +applications and other ODP implementations. The fourth is simply used to +designate the service stream associated with an individual ODP implementation. === 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. These changes may not be +backwards-compatible. Major release changes thus potentially affect ODP +applications as well as implementations. === Point releases === -General bug fixes and other non API altering changes are gathered and a release -made every month if sufficient change has accumulated. +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 typographic corrections to API header file +documentation, other additional documentation, extensions or corrections to +the validation test suite, additions or corrections to 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 (Impl) === -Platform specific free form text relating to the version. +Platform specific free form text relating to the version. 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. == 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 | 51 ++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 11 deletions(-) -- 2.7.4