On 09/29/2014 09:24 PM, Mike Holmes wrote:
Signed-off-by: Mike Holmes <mike.hol...@linaro.org>
---
release.dox | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 54 insertions(+)
create mode 100644 release.dox
diff --git a/release.dox b/release.dox
new file mode 100644
index 0000000..53301ac
--- /dev/null
+++ b/release.dox
@@ -0,0 +1,54 @@
+/* Copyright (c) 2014, Linaro Limited
+ * All rights reserved
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+@page release Release Management
+@tableofcontents
+@section release_numbering Numbering
+
+The API uses a three digit release number, for ODP this number refers to
+- The API header definitions
+- The reference implementation (linux-generic)
+- The documentation
+- The API test & validation suite that certifies each of the above.
+
+The header file odp_version.h contains helper macros for dealing with ODP
versions in application code.
+
+@note The version refers to API source compatibility and not binary
compatibility.
+Every change in API version will require a recompilation, relinking will not
be sufficient.
+
+The ODP API major.minor version will only change at well-defined release
points.
+A release will be tagged @code ODP-<major>.<minor> @endcode and bug fix releases on the platform
will be tagged @code ODP-<major>.<minor>.<sub> @endcode first bug fix release sub = 1.
+
+@subsection major Major
+The major digit is the ODP API generation.
+A change to this digit indicates a break in backwards compatibility.
+@note The incompatibility covers the whole ODP API, however the change may be
a tiny change to an esoteric function that is not used by a given application.
+
+- Altering API signature
+- Altering a structure other than adding optional items at the end.
+- Changing the required calling sequence for APIs
+- Changes to the installed structure i.e. the output from "make install" moves
a file in a way that breaks compilation.
+- New element to an enum that is an output from ODP
+
+@subsection minor Minor
+The minor digit is for changes that are backwards compatible.
+For example changes such as the addition of a new API.
+Existing application code shall not have to change if the new API is not used.
+- Adding a new struct
+- Adding a new function
+- Adding an additional alternate API to an existing one.
+- New element to an enum that is an input to ODP
+
+@subsection sub Sub
+The sub digit is used for backward compatible changes
+Any existing app should work as before with the caveat that a bug fix may
change the executable behavior (hopefully improve it)
+- Optimize the implementation
+- Documentation updates
+- bug fixes in implementation
That is a version of API and should not be related to any
implementation.
+
+*/
IMO having only Major number for backward incompatible changes is not
enough. I assume each our release during the next year won't be backward
compatible, so we will bump major number too often.
I imagine versions in a following way:
1. Major:
- Major architectural changes like buffer/packet managements changes
- new big sets of API added
2. Minor: your description for 'major' version
3. Sub: your description for 'minor' version + Documentation updates
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
http://lists.linaro.org/mailman/listinfo/lng-odp
