ping On 18 December 2015 at 22:35, Bill Fischofer <[email protected]> wrote:
> > > On Fri, Dec 18, 2015 at 3:10 PM, Mike Holmes <[email protected]> > wrote: > >> Describe how changes to the public api are handled from release to >> release. >> >> Signed-off-by: Mike Holmes <[email protected]> >> > > Reviewed-and-Tested-by: Bill Fischofer <[email protected]> > > >> --- > > doc/process-guide/release-guide.adoc | 108 >> +++++++++++++++++++++++++++++++++++ >> platform/Makefile.inc | 3 + >> test/api_test/Makefile.am | 3 + >> test/validation/Makefile.am | 3 + >> 4 files changed, 117 insertions(+) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index f5d29d2..5bef890 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -35,6 +35,8 @@ image::../images/simple_release_git.png[align="center"] >> >> Regular bug fixes, and implementation changes occur directly to master. >> >> + >> +[[anchor-1]] >> == Branch acceptance criteria == >> ODP has three branches one for general bug fixes and improvements on >> linux-generic, testing and examples (master). The second branch is for >> API >> @@ -134,3 +136,109 @@ made every month if sufficient change has >> accumulated. >> >> === Implementation (Impl) === >> Platform specific free form text relating to the version. >> + >> +== Deprecating part of the API >> +Deleting or changing the published API follows the normal >> <<anchor-1,process>>, with the following additional rules: >> + >> +* A deprecated indication is applied to the old API using the @deprecated >> +doxygen syntax. >> +* For a function change the old API it is additionally marked using the >> +ODP_DEPRECATED preprocessor macro. >> +* The CHANGELOG will have an entry in the API change section. >> +* The Release Manager will resolve the duration for which the deprecated >> API. >> +will be supported, and determine which future release it will be applied >> to. + >> + >> +The more complex use cases are elaborated below. >> + >> +=== Changing a function >> +A new function will be added with the new behavior. The old function >> will remain and be marked by both a documentation entry and a compiler >> warning. >> +For a function change the new API will be used in the examples, >> test/performance and >> +test/miscellaneous directories. >> +The new API must have comparable coverage to the old API. >> + >> + >> +[source,c] >> +---- >> +/** >> + * Create a foo >> + * >> + * @deprecated This API needs to take a count and will be deleted. >> + * The replacement API will be odp_bar_create(); >> + * >> + * @param name ... >> + */ >> +odp_foo_t odp_foo_create(const char *name) ODP_DEPRECATED; >> + >> +/** >> + * Create a bar >> + * >> + * @param name ... >> + */ >> +odp_foo_t odp_bar_create(const char *name, int count); >> +---- >> + >> +=== Deleting a function >> +When deleting a function it will be be indicated in the documentation >> and via a >> +compiler warning. >> + >> +[source,c] >> +---- >> +/** >> + * Create a foo >> + * >> + * @deprecated This API will be removed because platforms now take care >> of this >> + * >> + * @param name ... >> + */ >> +odp_foo_t odp_foo_create(const char *name) ODP_DEPRECATED; >> +---- >> + >> +=== Changing a struct member >> +When changing a struct member it will be indicated in the documentation. >> + >> +[source,c] >> +---- >> +/** >> + * An initialization struct >> + */ >> +typedef struct foo_init_t { >> + /** Maximum number of worker threads */ >> + int num_worker; >> + >> + /** >> + * Maximum number of control threads >> + * @deprecated this is now number_of_control >> + */ >> + int num_control; >> + int other_items; >> + int number_of_control; >> +---- >> + >> +The implementation of the structs initialization function must be >> updated to cover the new element. >> +[source,c] >> +---- >> +void odp_foo_param_init(foo_init_t param) { >> + ... >> + param->number_of_control = 20; >> +} >> +---- >> + >> +=== Deleting a struct member >> +When deleting a struct member it will be indicated in the documentation. >> + >> +[source,c] >> +---- >> +/** >> + * An initialization struct >> + */ >> +typedef struct foo_init_t { >> + /** Maximum number of worker threads */ >> + int num_worker; >> + >> + /** >> + * Maximum number of control threads >> + * @deprecated this is no longer needed, it is automatically >> inferred. >> + */ >> + int num_control; >> + int other_items; >> +---- >> diff --git a/platform/Makefile.inc b/platform/Makefile.inc >> index 5d589b1..46a3baa 100644 >> --- a/platform/Makefile.inc >> +++ b/platform/Makefile.inc >> @@ -16,6 +16,9 @@ GIT_DESC = `$(top_srcdir)/scripts/get_impl_str.sh >> $(top_srcdir)` >> AM_CFLAGS += "-DGIT_HASH=$(GIT_DESC)" >> AM_CFLAGS += -DPLATFORM=${with_platform} >> >> +#The implementation will need to retain the deprecated implementation >> +AM_CFLAGS += -Wno-deprecated-declarations >> + >> odpapiincludedir= $(includedir)/odp/api >> odpapiinclude_HEADERS = \ >> $(top_srcdir)/include/odp/api/align.h \ >> diff --git a/test/api_test/Makefile.am b/test/api_test/Makefile.am >> index fcdba48..97ca5df 100644 >> --- a/test/api_test/Makefile.am >> +++ b/test/api_test/Makefile.am >> @@ -11,3 +11,6 @@ noinst_HEADERS = \ >> $(top_srcdir)/test/test_debug.h >> >> dist_odp_ring_SOURCES = odp_ring_test.c odp_common.c >> + >> +#The tests will need to retain the deprecated test implementation >> +AM_CFLAGS += -Wno-deprecated-declarations >> \ No newline at end of file >> diff --git a/test/validation/Makefile.am b/test/validation/Makefile.am >> index 4e36494..527e44b 100644 >> --- a/test/validation/Makefile.am >> +++ b/test/validation/Makefile.am >> @@ -19,3 +19,6 @@ ODP_MODULES = buffer \ >> system >> >> SUBDIRS = common $(ODP_MODULES) >> + >> +#The tests will need to retain the deprecated test implementation >> +AM_CFLAGS += -Wno-deprecated-declarations >> \ No newline at end of file >> -- >> 2.5.0 >> >> _______________________________________________ >> lng-odp mailing list >> [email protected] >> 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 [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
