preparation, please wait …​ comparing ABIs …​ comparing APIs …​ creating compatibility report …​ result: COMPATIBLE total "Binary" compatibility problems: 0, warnings: 0 total "Source" compatibility problems: 0, warnings: 0

----

== Releases ==
All releases are from a tag in the master branch of the ODP git
repository. Recall that ODP consists of three separate components:

* An API Specification
* Multiple independently owned and maintained _implementations_ of the ODP API
* A Validation Test Suite that tests implementation conformance to the ODP API

Included with the main ODP git repository is the `odp-linux` reference
implementation of the ODP API, and it also has an associated service stream
that is independent of all other ODP implementations. This means that the ODP
release naming conventions address the needs of all three of these components,
which is accomplished via a multi-level structure using the format:

*v<Generation>.<Major>.<Minor>.<Point>*

This is used as the tag from which all ODP releases are published and is also
used as the release identifier in the CHANGELOG for each release.  The first
three of these digits represent the ODP API level, and these reflect three
types of API changes with differing frequencies and impact to applications and
other ODP implementations. A fourth digit is used to reflect changes to other
items included within the ODP git repository. In addition, each individual ODP
implementation will have its own service stream identifier that is defined
using whatever conventions meet its needs.

=== Generation releases ===
A generation release indicates a major completion of work, and a possible
change in direction for the API. Generation release changes are approved by the
LNG Steering Committee, which is the governing body for ODP.

=== Major releases ===
Major (API) releases are used when new APIs or capabilities are introduced or
changes are made to existing APIs that are not backwards-compatible. Major
release changes thus potentially affect ODP applications as well as
implementations.

=== Minor releases ===
Minor (API) releases are used when new APIs or capabilities are introduced or
changes are made to existing APIs in a backwards-compatible manner. Examples
of these might be wording changes in API documentation, or introducing new
APIs that are orthogonal to the existing set of APIs and hence have no impact
on existing applications that do not make use of them. Minor release changes
should therefore have no impact on existing ODP applications but will have
impact for ODP implementations that need to support these API additions and
changes.

NOTE: The first three digits of the release name are the API version returned
by the `odp_version_api_str()` API.

=== Point releases ===
General bug fixes and other non API altering changes are gathered and a
release made every month if sufficient change has accumulated. Examples of a
point release would be additional documentation, extensions or corrections to
the validation test suite, additions or corrections to helpers, example
programs, etc. No API changes are permitted in a point release, so ODP
applications are not impacted.  Other ODP implementations _may_ be impacted
if, for example, a bug is fixed in a validation test that results in a latent
bug in other implementations being exposed.

=== Implementation Service Strings ===
Beyond the four-digit release name, platform specific free form text is used
to capture the service level of each ODP implementation. This field is for the
sole use of implementations to represent their individual service streams. Its
format may vary between implementations. For example, the `odp-linux`
reference implementation uses a simple incrementing digit (0, 1, 2,
etc.). Other implementations may use `Build xxxx` or something similar.
Changes in this designator have no impact on and may be ignored by other ODP
implementations. The only changes that ODP applications should see is
corrected functional or performance behavior when running on that specific ODP
implementation.

NOTE: The full four-digit release name plus implementation service string as
well as other platform-specific identification information is returned by the
`odp_version_impl_str()` API. This may be useful, for example, in logging an
error to include in a bug report to the vendor that owns and supports this ODP
implementation. The release-independent name of a given implementation (for
identification purposed) is supplied by the `odp_version_impl_name()` API.

== 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_DEPRECATE() 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_DEPRECATE(odp_foo_create)(const char *name);

/**
 * 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_DEPRECATE(odp_foo_create)(const char *name);
----

=== 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;
----