Merged. On 3 January 2016 at 22:37, Mike Holmes <[email protected]> wrote:
> 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 > > > -- 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
