On 16 December 2015 at 05:50, Maxim Uvarov <maxim.uva...@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.hol...@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
_______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
