Describe how changes to the public api are handled from release to release.
Signed-off-by: Mike Holmes <[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
