[daisy-pipeline.wiki] push by - Created wiki page through web user interface. on 2013-08-26 14:21 GMT

[daisy-p...@googlecode.com]

Revision: 575d3e89e543
Branch: default
Author: bert...@gmail.com
Date: Mon Aug 26 14:21:05 2013 UTC
Log: Created wiki page through web user interface.
http://code.google.com/p/daisy-pipeline/source/detail?r=575d3e89e543&repo=wiki

Added:
/Versioning.wiki

=======================================
--- /dev/null
+++ /Versioning.wiki Mon Aug 26 14:21:05 2013 UTC
@@ -0,0 +1,81 @@
+#summary Semantic Versioning: API definition and commit/release policy
+
+= Introduction =
+
+From now on we will follow the rules of "Semantic Versioning" (SemVer)
described at http://semver.org.
+
+= API definition =
+
+SemVer requires us to declare a public API:
+
+ "This API could be declared in the code itself or exist strictly in
documentation. However it is done, it should be precise and comprehensive."
+
+== Java ==
+
+API = everything that is declared public (or protected?) in exported
packages.
+
+(what about implementations of services that are activated through DS?
these packages are exported, but they are not always part of an API.)
+
+== XProc ==
+
+API = the signature of steps declared in files (`p:declare-step` /
`p:pipeline` / `p:library`) listed in the the bundle's catalog.xml.
+
+(question: what happens with transitive imports in XProc? and
sub-pipelines in an imported pipeline?)
+
+== XSLT ==
+
+API = templates/functions declared "public" using comments.
+
+Because in XSLT there is no way to limit the visibility of code, we need
to declare the API using comments in the code. Ideally we separate
the "public" templates/functions in the head of the file and move the rest
below.
+
+(idea: should we have a tool that generates the documentation of our
public API? The tool would of course invoke javadoc, maybe xprocdoc, and
maybe a custom tool that extracts the public XSLT templates/functions.)
+
+= Commit/release policy =
+
+SemVer states that:
+
+ 2. A normal version number MUST take the form X.Y.Z where X, Y, and Z
are non-negative integers, and MUST NOT contain leading zeroes. X is the
major version, Y is the minor version, and Z is the patch version. Each
element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
+ [...]
+
+ 6. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards
compatible bug fixes are introduced. A bug fix is defined as an internal
change that fixes incorrect behavior.
+
+ 7. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards
compatible functionality is introduced to the public API. It MUST be
incremented if any public API functionality is marked as deprecated. It MAY
be incremented if substantial new functionality or improvements are
introduced within the private code. It MAY include patch level changes.
Patch version MUST be reset to 0 when minor version is incremented."
+
+ 8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards
incompatible changes are introduced to the public API. It MAY include minor
and patch level changes. Patch and minor version MUST be reset to 0 when
major version is incremented.
+
+For us, this translates into the following commit/release policy:
+
+== When we do a pull request ==
+
+We make sure that the current POM version (which should be a SNAPSHOT) is
coherent with all the changes since the last release.
+
+If the current set of changes:
+
+(note, in the following x,y,z > 0)
+
+ # brings no new functionality (i.e. does backward compatible bug fixes,
code cleanup, etc. only), we stay at the current SNAPSHOT version
+ # brings new functionality but backward-compatible: we need to make sure
the MINOR version is increased compared to the previous fixed release
+ * if the current SNAPSHOT version is x.0.0-SNAPSHOT, it means the
MAJOR version has been increased already, so the current SNAPSHOT version
does not need to be changed
+ * if the current SNAPSHOT version is x.y.0-SNAPSHOT, it means the
MINOR version has been increased already, so the current SNAPSHOT version
does not need to be changed
+ * if the current SNAPSHOT version is x.y.z-SNAPSHOT, it means only the
PATCH version has been increased so far, so we need to increase the MINOR
version instead; we change the current SNAPSHOT to x.y+1.0-SNAPSHOT
+ # brings new functionality and breaks backward-compatibililty: we need
to make sure the MAJOR version is increased compared to the previous fixed
release
+ * if the current SNAPSHOT version is x.0.0-SNAPSHOT, it means the
MAJOR version has been increased already, so the current SNAPSHOT version
does not need to be changed
+ * if the current SNAPSHOT version is x.y.0-SNAPSHOT, it means only the
MINOR version has been increased so far; we need to increase the MAJOR
version instead; we change the current SNAPSHOT to x+1.0.0-SNAPSHOT
+ * if the current SNAPSHOT version is x.y.z-SNAPSHOT, it means only the
PATCH version has been increased so far; we need to increase the MAJOR
version instead; we change the current SNAPSHOT to x+1.0.0-SNAPSHOT
+ # (corner case) reverts previous changes since the last release: we must
make sure that if we had increased the MINOR or MAJOR versions because of
the previous changes, we decrease the current SNAPSHOT version accordingly.
+
+So, in cases 1, 2 and 3, we only need to look at the current set of
changes and the current SNAPSHOT version number. In case 4 we need to look
at the overall set of changes since the last release, but this is a corner
case.
+
+== When we do a release ==
+If there are no changes (no commits since the last release, except for the
one that says "prepare the new POM for the next iteration version"), we do
nothing.
+
+Otherwise, we:
+
+ * update the version to to the fixed version number (1.0.0-SNAPSHOT
becomes 1.0.0)
+ * deploy to Sonatype OSS Repo (it gets to a staged release repo)
+ * at some point soon after, "close" and check the release, then
confirm the sync to Maven Central
+ * commit
+ * update the version to the next snapshot, i.e. by default increase the
PATCH version + SNAPSHOT (which is the minimum next version, after 1.0.0,
it becomes 1.0.1-SNAPSHOT).
+ * commit
+
+We publish fixed releases whenever we do a public release of the distro,
or potentially whenever a user asks for a patch or new feature.