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 >
_______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
