| Message ID | 1450202766-30096-3-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
On Tue, Dec 15, 2015 at 12:06 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > Describe how changes to the public api are handled from release to release. > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/process-guide/release-guide.adoc | 38 > ++++++++++++++++++++++++++++++++++++ > 1 file changed, 38 insertions(+) > > diff --git a/doc/process-guide/release-guide.adoc > b/doc/process-guide/release-guide.adoc > index f5d29d2..d932118 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -134,3 +134,41 @@ made every month if sufficient change has accumulated. > > === Implementation (Impl) === > Platform specific free form text relating to the version. > + > +== Deprecated APIs > + > +Whenever an API is changed as part of an api-next patch the following > rules > +apply to provide a warning to implementers and users. > + > +* A patch will be applied to api-next that adds the deprecated indication > to > +the old public API in odp/include > +* A patch will be applied to api-next that adds the new API and removes > the > +old, in these cases the implementation and tests must also change at the > same > +time to ensure that CI shows no regressions in the api-next branch. > +* When the Release Manager has scheduled the api change to be released in > a > +future version, the initial deprecated patch will be moved to next branch > and > +released in the next release cycle. > +* When at a minim of one release cycle has passed, and possibly longer as > +specified by the Release Manager the complete change will be merged to > next and > +then released in the next cycle. > This is good, however we still need to cover the case where the change is not the removal of an API but a change to its type signature (e.g., the anticipated change to odp_cls_cos_create() to add a new odp_cls_cos_param_t parameter to the argument list). In this case it's the old type signature that is being deprecated rather than the function name. Since we're handling this via documentation using @deprecated then perhaps just emphasize that the explanatory text should detail the nature of the anticipated change. > + > +NOTE: Any given release never supports two versions of an API > + > +.Marking a deprecated API element > +[source,c] > +---- > +/** > + * Get buffer handle from event > + * > + * Converts an ODP_EVENT_BUFFER type event to a buffer. > + * > + * @deprecated This api will be removed for some good reason defined here > + * > + * @param ev Event handle > + * > + * @return Buffer handle > + * > + * @see odp_event_type() > + */ > +odp_buffer_t odp_buffer_from_event(odp_event_t ev); > It's confusing to use a real ODP API like this. I'd prefer to see this covered with an artificial API such as: /** * Create a foo * * @deprecated This API will be removed since foos are being replaced by bars. The replacement API will be * odp_bar_create(); * * @param name ... */ odp_foo_t odp_foo_create(const char *name); Or in the case of a change in type signature: * @deprecated This API's type signature will be changed add an new parameter to specify the color of the foo to be created. The new call will be odp_foo_create(const char *name, odp_foo_color_t color); > +---- > \ No newline at end of file > This looks like an error marker inserted by format-patch. Check and correct. > -- > 2.5.0 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
On 15 December 2015 at 18:42, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > On Tue, Dec 15, 2015 at 12:06 PM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Describe how changes to the public api are handled from release to >> release. >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> doc/process-guide/release-guide.adoc | 38 >> ++++++++++++++++++++++++++++++++++++ >> 1 file changed, 38 insertions(+) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index f5d29d2..d932118 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -134,3 +134,41 @@ made every month if sufficient change has >> accumulated. >> >> === Implementation (Impl) === >> Platform specific free form text relating to the version. >> + >> +== Deprecated APIs >> + >> +Whenever an API is changed as part of an api-next patch the following >> rules >> +apply to provide a warning to implementers and users. >> + >> +* A patch will be applied to api-next that adds the deprecated >> indication to >> +the old public API in odp/include >> +* A patch will be applied to api-next that adds the new API and removes >> the >> +old, in these cases the implementation and tests must also change at the >> same >> +time to ensure that CI shows no regressions in the api-next branch. >> +* When the Release Manager has scheduled the api change to be released >> in a >> +future version, the initial deprecated patch will be moved to next >> branch and >> +released in the next release cycle. >> +* When at a minim of one release cycle has passed, and possibly longer as >> +specified by the Release Manager the complete change will be merged to >> next and >> +then released in the next cycle. >> > > This is good, however we still need to cover the case where the change is > not the removal of an API but a change to its type signature (e.g., the > anticipated change to odp_cls_cos_create() to add a new odp_cls_cos_param_t > parameter to the argument list). In this case it's the old type signature > that is being deprecated rather than the function name. Since we're > handling this via documentation using @deprecated then perhaps just > emphasize that the explanatory text should detail the nature of the > anticipated change. > How would we do this differently - I might not be fully understanding @deprecated applies to anything doxygen can comment and the reason for the change would be listed, we can add a second example for a change in params to show that you describe the reason for the change that will be coming. > > >> + >> +NOTE: Any given release never supports two versions of an API >> + >> +.Marking a deprecated API element >> +[source,c] >> +---- >> +/** >> + * Get buffer handle from event >> + * >> + * Converts an ODP_EVENT_BUFFER type event to a buffer. >> + * >> + * @deprecated This api will be removed for some good reason defined >> here >> + * >> + * @param ev Event handle >> + * >> + * @return Buffer handle >> + * >> + * @see odp_event_type() >> + */ >> +odp_buffer_t odp_buffer_from_event(odp_event_t ev); >> > > It's confusing to use a real ODP API like this. I'd prefer to see this > covered with an artificial API such as: > > /** > * Create a foo > * > * @deprecated This API will be removed since foos are being replaced by > bars. The replacement API will be > * odp_bar_create(); > * > * @param name ... > */ > odp_foo_t odp_foo_create(const char *name); > > Or in the case of a change in type signature: > > * @deprecated This API's type signature will be changed add an new > parameter to specify the color of the foo to be created. The new call will > be odp_foo_create(const char *name, odp_foo_color_t color); > > Sure, no problem. > +---- >> \ No newline at end of file >> > > This looks like an error marker inserted by format-patch. Check and > correct. > I know what this is, editor sometimes thinks it is helping :) thanks > > >> -- >> 2.5.0 >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
On 12/15/2015 21:06, Mike Holmes wrote: > Describe how changes to the public api are handled from release to release. > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/process-guide/release-guide.adoc | 38 ++++++++++++++++++++++++++++++++++++ > 1 file changed, 38 insertions(+) > > diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc > index f5d29d2..d932118 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -134,3 +134,41 @@ made every month if sufficient change has accumulated. > > === Implementation (Impl) === > Platform specific free form text relating to the version. > + > +== Deprecated APIs > + > +Whenever an API is changed as part of an api-next patch the following rules > +apply to provide a warning to implementers and users. > + > +* A patch will be applied to api-next that adds the deprecated indication to > +the old public API in odp/include That sentence should never be in product documentation. Plans can be in Jira cards, bugs, mailing list, but published docs should relay only on work which is already done. > +* A patch will be applied to api-next that adds the new API and removes the > +old, in these cases the implementation and tests must also change at the same > +time to ensure that CI shows no regressions in the api-next branch. same here. > +* When the Release Manager has scheduled the api change to be released in a > +future version, the initial deprecated patch will be moved to next branch and > +released in the next release cycle. > +* When at a minim of one release cycle has passed, and possibly longer as > +specified by the Release Manager the complete change will be merged to next and > +then released in the next cycle. Release Manager scheduled in next release cycle ... It's it too complex to read and understand when and what will be done. How about be more community friendly in sentences? Something like: "" ODP API provides special API to mark function and data types as deprecated. Marking function as deprecated means that ODP Community will support all functionality for that function, validation tests and test execution in CI system. Because of support of both new API and deprecated adds additional load and increase complexity marking functions as deprecated will happen only for specific reason. That reason should be valuable, discussed in ODP community meetings, recorded in mailing list and corresponding bug entry should be open. Also some transition period for supporting old API should be defined. > + > +NOTE: Any given release never supports two versions of an API > + That is not what deprecated means. I.e. deprecated means absolutely opposite - support old version and new at the same time. > +.Marking a deprecated API element > +[source,c] > +---- > +/** > + * Get buffer handle from event > + * > + * Converts an ODP_EVENT_BUFFER type event to a buffer. > + * > + * @deprecated This api will be removed for some good reason defined here doxygen is not enough I think. Also here might be some short description and link to bug. +odp_buffer_t odp_buffer_from_event(odp_event_t ev) ODP_DEPRECATED; and compile with: -Wno-deprecated-declarations Maxim. > + * > + * @param ev Event handle > + * > + * @return Buffer handle > + * > + * @see odp_event_type() > + */ > +odp_buffer_t odp_buffer_from_event(odp_event_t ev); > +---- > \ No newline at end of file
On 16 December 2015 at 05:50, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > On 12/15/2015 21:06, Mike Holmes wrote: > >> Describe how changes to the public api are handled from release to >> release. >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> doc/process-guide/release-guide.adoc | 38 >> ++++++++++++++++++++++++++++++++++++ >> 1 file changed, 38 insertions(+) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index f5d29d2..d932118 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -134,3 +134,41 @@ made every month if sufficient change has >> accumulated. >> === Implementation (Impl) === >> Platform specific free form text relating to the version. >> + >> +== Deprecated APIs >> + >> +Whenever an API is changed as part of an api-next patch the following >> rules >> +apply to provide a warning to implementers and users. >> + >> +* A patch will be applied to api-next that adds the deprecated >> indication to >> +the old public API in odp/include >> > That sentence should never be in product documentation. Plans can be in > Jira cards, bugs, mailing list, but published docs should relay only on > work > which is already done. I dont follow the rationale that this is the wrong place, this is the document that does describe how we will operate, we dont specify which patch just how they will be used. > > > +* A patch will be applied to api-next that adds the new API and removes >> the >> +old, in these cases the implementation and tests must also change at the >> same >> +time to ensure that CI shows no regressions in the api-next branch. >> > same here. describing how we operate is the purpose of this doc > > > +* When the Release Manager has scheduled the api change to be released in >> a >> +future version, the initial deprecated patch will be moved to next >> branch and >> +released in the next release cycle. >> +* When at a minim of one release cycle has passed, and possibly longer as >> +specified by the Release Manager the complete change will be merged to >> next and >> +then released in the next cycle. >> > Release Manager scheduled in next release cycle ... It's it too complex > to read and understand when and what will be done. How about be more > community friendly in sentences? Something like: > We can certainly try to make it clearer and put the points on a diagram to show how they relate in time. > > "" > ODP API provides special API to mark function and data types as deprecated. > This is not true, there is no API only a doxygen comment. > Marking function as deprecated means that ODP Community will support all > functionality for that function, validation tests and test execution in CI > system. > No, deprecated means literally that you should stop using something. In our case becasue it will change and you can view the new version in api-next. > Because of support of both new API and deprecated adds additional load and > increase complexity marking functions as deprecated will happen only for > specific reason. We will mark them deprecated when the current API can be shown to be deficient and a better alternative has already been proven in api-next. That reason should be valuable, discussed in ODP community meetings, > recorded in mailing list and corresponding bug entry should be open. Yes, that is why we created api-next so that the community can comment and give feedback > Also some transition > period for supporting old API should be defined. > > The release manager role is the one that ensures that all the process has been completed and schedules the change to actually occur, at no point will the old api be supported concurrently unless it is in a long term support version. The period for which the deprecated element is flagged will vary and will generally be reached by consensus in api-next discussion. > + >> +NOTE: Any given release never supports two versions of an API >> + >> > > That is not what deprecated means. I.e. deprecated means absolutely > opposite - support old version > and new at the same time. No, "*Deprecation* is an attribute applied to a computer software <https://en.wikipedia.org/wiki/Computer_software> feature, characteristic, or practice to indicate that it should be avoided (often because it is being superseded). " It says nothing about supporting it in parallel with a new variant. ODP support during this period comes in the form that the old api will still work while the warning is in effect that you should plan on stopping using it. You don't have to stop using it, you could remain on that release. > > > +.Marking a deprecated API element >> +[source,c] >> +---- >> +/** >> + * Get buffer handle from event >> + * >> + * Converts an ODP_EVENT_BUFFER type event to a buffer. >> + * >> + * @deprecated This api will be removed for some good reason defined >> here >> > doxygen is not enough I think. Also here might be some short description > and link to bug. > > +odp_buffer_t odp_buffer_from_event(odp_event_t ev) ODP_DEPRECATED; > and compile with: -Wno-deprecated-declarations > > Maxim. > > + * >> + * @param ev Event handle >> + * >> + * @return Buffer handle >> + * >> + * @see odp_event_type() >> + */ >> +odp_buffer_t odp_buffer_from_event(odp_event_t ev); >> +---- >> \ No newline at end of file >> > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
On 12/16/2015 20:22, Mike Holmes wrote: > > > On 16 December 2015 at 05:50, Maxim Uvarov <maxim.uvarov@linaro.org > <mailto:maxim.uvarov@linaro.org>> wrote: > > On 12/15/2015 21:06, Mike Holmes wrote: > > Describe how changes to the public api are handled from > release to release. > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > --- > doc/process-guide/release-guide.adoc | 38 > ++++++++++++++++++++++++++++++++++++ > 1 file changed, 38 insertions(+) > > diff --git a/doc/process-guide/release-guide.adoc > b/doc/process-guide/release-guide.adoc > index f5d29d2..d932118 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -134,3 +134,41 @@ made every month if sufficient change has > accumulated. > === Implementation (Impl) === > Platform specific free form text relating to the version. > + > +== Deprecated APIs > + > +Whenever an API is changed as part of an api-next patch the > following rules > +apply to provide a warning to implementers and users. > + > +* A patch will be applied to api-next that adds the > deprecated indication to > +the old public API in odp/include > > That sentence should never be in product documentation. Plans can > be in > Jira cards, bugs, mailing list, but published docs should relay > only on work > which is already done. > > > I dont follow the rationale that this is the wrong place, this is the > document that does describe how we will operate, we dont specify which > patch just how they will be used. Sorry, for first read I thought that want to send patch to api-next to mark functions as deprecated. Instead of current one. But you just defining list of rules for such deprecated patch. It's a little bit confusing senescence for me as non native English. Might be: 1. add ":" after "users". So reader can expect some list. 2. Rephrase sentence to: "Patch which marks existence api (odp/include) with deprecated indication should be applied on api-next first. Same way as all other api changes patches." (if we name it "rules", not "plans" - it has to be not future form, right? I.e. have to, must). > > > +* A patch will be applied to api-next that adds the new API > and removes the > +old, in these cases the implementation and tests must also > change at the same > +time to ensure that CI shows no regressions in the api-next > branch. > > same here. > > describing how we operate is the purpose of this doc That also I understood wrongly. But replace old by new is not deprecation. It's just api replacement. That should be in api-next branch description. And chapter Deprecated APIs should have rules only suitable for deprecation. > > > +* When the Release Manager has scheduled the api change to be > released in a > +future version, the initial deprecated patch will be moved to > next branch and > +released in the next release cycle. > +* When at a minim of one release cycle has passed, and > possibly longer as > +specified by the Release Manager the complete change will be > merged to next and > +then released in the next cycle. > > Release Manager scheduled in next release cycle ... It's it too > complex > to read and understand when and what will be done. How about be more > community friendly in sentences? Something like: > > > We can certainly try to make it clearer and put the points on a > diagram to show how they relate in time. > My point is - it's easy to mark function as deprecated. But you never know what time will take transition period that everybody will stop using it. Linux kernel has some deprecated function which warn for years. And I think that right thing will be discussion before next big release if we want to remove some specific functions. > > "" > ODP API provides special API to mark function and data types as > deprecated. > > > This is not true, there is no API only a doxygen comment. everything what is in ./include/odp/api we consider as API, right? include/odp/api/hints.h #define ODP_DEPRECATED __attribute__((__deprecated__)) > > Marking function as deprecated means that ODP Community will > support all > functionality for that function, validation tests and test > execution in CI system. > > > No, deprecated means literally that you should stop using something. > In our case becasue it will change and you can view the new version in > api-next. It depends from with point of view you are looking. Yes it says - stop using it. But that api should still have implementation and validation tests for linux-generic. I.e. we have to support it for some time until it's completely removed. > Because of support of both new API and deprecated adds additional > load and > increase complexity marking functions as deprecated will happen > only for > specific reason. > > > We will mark them deprecated when the current API can be shown to be > deficient and a better alternative has already been proven in api-next. > yes, it was just sentence to document. That there should be specific reason. > That reason should be valuable, discussed in ODP community meetings, > recorded in mailing list and corresponding bug entry should be open. > > > Yes, that is why we created api-next so that the community can > comment and give feedback also just sentence to your process doc - where exactly we store that specific reason. > Also some transition > period for supporting old API should be defined. > > > The release manager role is the one that ensures that all the process > has been completed and schedules the change to actually occur, at no > point will the old api be supported concurrently unless it is in a > long term support version. The period for which the deprecated element > is flagged will vary and will generally be reached by consensus in > api-next discussion. > It does not matter who will control that process. Idea is that document should say where it will be documented. I.e. each developer can go to bug entry find information that for example function x() is deprecated in odp1.5 and will be removed in odp2.0, use y(). Might be doxygen can have all information about time. btw, can we in doxygen have list of all things marked as @deprecated? That list will be very easy to review. > > + > +NOTE: Any given release never supports two versions of an API > + > > > That is not what deprecated means. I.e. deprecated means > absolutely opposite - support old version > and new at the same time. > > > No, "*Deprecation* is an attribute applied to a computer software > <https://en.wikipedia.org/wiki/Computer_software> feature, > characteristic, or practice to indicate that it should be avoided > (often because it is being superseded). " > It says nothing about supporting it in parallel with a new variant. > ODP support during this period comes in the form that the old api > will still work while the warning is in effect that you should plan on > stopping using it. You don't have to stop using it, you could remain > on that release. Yes. Again, from which side are you looking from odp apps developer or from odp developer. Both api have to work. That means they should pass and have validation tests, correct implementation and etc. > > > +.Marking a deprecated API element > +[source,c] > +---- > +/** > + * Get buffer handle from event > + * > + * Converts an ODP_EVENT_BUFFER type event to a buffer. > + * > + * @deprecated This api will be removed for some good reason > defined here > > doxygen is not enough I think. Also here might be some short > description and link to bug. > > +odp_buffer_t odp_buffer_from_event(odp_event_t ev) ODP_DEPRECATED; > and compile with: -Wno-deprecated-declarations > > Maxim. > > + * > + * @param ev Event handle > + * > + * @return Buffer handle > + * > + * @see odp_event_type() > + */ > +odp_buffer_t odp_buffer_from_event(odp_event_t ev); > +---- > \ No newline at end of file > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > https://lists.linaro.org/mailman/listinfo/lng-odp > > > > > -- > Mike Holmes > Technical Manager - Linaro Networking Group > Linaro.org <http://www.linaro.org/>***│ *Open source software for ARM SoCs >
diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc index f5d29d2..d932118 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -134,3 +134,41 @@ made every month if sufficient change has accumulated. === Implementation (Impl) === Platform specific free form text relating to the version. + +== Deprecated APIs + +Whenever an API is changed as part of an api-next patch the following rules +apply to provide a warning to implementers and users. + +* A patch will be applied to api-next that adds the deprecated indication to +the old public API in odp/include +* A patch will be applied to api-next that adds the new API and removes the +old, in these cases the implementation and tests must also change at the same +time to ensure that CI shows no regressions in the api-next branch. +* When the Release Manager has scheduled the api change to be released in a +future version, the initial deprecated patch will be moved to next branch and +released in the next release cycle. +* When at a minim of one release cycle has passed, and possibly longer as +specified by the Release Manager the complete change will be merged to next and +then released in the next cycle. + +NOTE: Any given release never supports two versions of an API + +.Marking a deprecated API element +[source,c] +---- +/** + * Get buffer handle from event + * + * Converts an ODP_EVENT_BUFFER type event to a buffer. + * + * @deprecated This api will be removed for some good reason defined here + * + * @param ev Event handle + * + * @return Buffer handle + * + * @see odp_event_type() + */ +odp_buffer_t odp_buffer_from_event(odp_event_t ev); +---- \ No newline at end of file
Describe how changes to the public api are handled from release to release. Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/process-guide/release-guide.adoc | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+)