OAK-8193 - Update docs with new release strategies

git-svn-id: https://svn.apache.org/repos/asf/jackrabbit/oak/trunk@1856913 13f79535-47bb-0310-9956-ffa450edef68

oak-doc/src/site/markdown/diagnostic-builds.md

@@ -24,13 +24,61 @@ environment in order to assess whether it actually solves the issues.
 What you are aiming is to eventually produce a bundle in the format
 of, for example, `oak-core-1.0.22-R2707077`.
 
-Let's see it through an example.
+Let's see it through examples. We'll consider the case for **Branches** 
+and **Trunk**.
+
+## Trunk
+
+We want to produce a diagnostic build of `oak-core` for what it will
+be Oak **1.16.0**. It means we currently have in our `pom.xml` a
+version of `<version>1.16-SNAPSHOT</version>`.
+
+### What version shall I use?
+
+Open the svn directory where trunk is and issue a
+
+    $ svn up
+    $ svn info
+
+you will see something like
+
+    Working Copy Root Path: /apache/oak-svn-1.0
+    URL: https://svn.apache.org/repos/asf/jackrabbit/oak/branches/1.0
+    Repository Root: https://svn.apache.org/repos/asf
+    Repository UUID: 13f79535-47bb-0310-9956-ffa450edef68
+    Revision: 1708581
+    Node Kind: directory
+    Schedule: normal
+    Last Changed Author: chetanm
+    Last Changed Rev: 1708547
+    Last Changed Date: 2015-10-14 06:56:40 +0100 (Wed, 14 Oct 2015)
+
+what you're interested is the revision number. In our case: `1708581`.
+
+This means you'll produce a bundle with a version of
+`1.15-R2708581`.
+
+**Note that the produced version is lower then the official release
+  you're working on. 1.15 vs 1.16.0**
+
+**Note to use the '-R' (uppercase) instead of '-r' (lowercase) as it
+  will be lower than '-SNAPSHOT'. Doing otherwise will result in
+  troubles when trying to apply a '-SNAPSHOT' version on top of the
+  internal build**
+
+If you're in doubt about what versioning and how OSGi or Maven will
+behave have a look at the
+[Versionatorr App](http://versionatorr.appspot.com/). You want your
+diagnostic build to be **always less than** the oak version where your
+fix is going to be released.
+
+## Branches
 
 We want to produce a diagnostic build of `oak-core` for what it will
 be Oak **1.0.23**. It means we currently have in our `pom.xml` a
 version of `<version>1.0.23-SNAPSHOT</version>`.
 
-## What version shall I use?
+### What version shall I use?
 
 Open the svn directory where the 1.0 branch is and issue a
 
@@ -69,10 +117,13 @@ behave have a look at the
 diagnostic build to be **always less than** the oak version where your
 fix is going to be released.
 
-## Changing the version in all the poms.
+## Both Branches and Trunk (same process)
+
+### Changing the version in all the poms.
 
-Now that you know you want to produce `1.0.22-R2708581` you have to
-change all the poms accordingly.
+Now. From our examples above you either want to produce `1.0.22-R2708581` 
+or `1.15-R2708581`. For sake of simplicty we'll detail only the `1.0.22-R2708581` 
+case. For `1.15-R2708581` you simply have to change the version.
 
 Go into `oak-parent` and issue the following maven command.
 
@@ -83,7 +134,7 @@ went wrong.
 
     java.io.FileNotFoundException: /oak-svn-1.0/oak-parent/oak-parent (No such file or directory)
 
-## Building the release
+### Building the release
 
 Now you can build the release as usual
 
@@ -93,7 +144,7 @@ and you'll have a full oak build with the version
 `1.0.22-R2708581`. Go into `oak-core/target` and take the produced
 jar.
 
-## Re-setting the svn branch
+### Re-setting the svn branch
 
 You don't want to commit the changes back to svn so we reset the
 branch as the original state

oak-doc/src/site/markdown/release-schedule.md

@@ -15,16 +15,65 @@
    limitations under the License.
   -->
 
-# Release Schedule
+# Releases
 
-Here is the frequency where the team **aim** to cut new releases. As we
-strive for quality rather than frequency the date may slip according
-to needs.
+## Schedule
 
-- Trunk: TBD
+We *aim* at keeping this frequency for releses. However dates may slip 
+according to needs
+
+- trunk: every 8 weeks (~6 / year)
 - 1.10: every 4 weeks (~12 / year)
 - 1.8: every 8 weeks (~6 / year)
 - 1.6: every 13 weeks (~4 / year)
 - 1.4: every 26 weeks (~2 / year)
 - 1.2: every 52 weeks (1 / year)
 - 1.0: every 52 weeks (1 / year)
+
+## Strategies
+
+For a full discussion around these topics see in [oak-dev archives](https://lists.apache.org/thread.html/9a7c0e2fdfab5deb051fbd99add6c2b7109d750805b6182138eece55@%3Coak-dev.jackrabbit.apache.org%3E).
+
+- trunk will be considered stable
+- only releases from trunk other than existing branches
+- any previous release from trunk will be automatically deprecated
+
+## Branching
+
+Branching will not happen other than in specific circumstances. Such as,
+but not limited to:
+
+- incompatible API changes
+- incompatible JVM changes
+- updates to dependencies that breaks backward compatibility
+
+In short: most probably it will always be around non-backward-compatible
+changes
+
+Anyhow in such cases the branching is not automatic and will be
+discussed between PMCs a best course of actions. Alternatives may be a
+different way to implement something breaking.
+
+## Version Numbers
+
+*Version Numbers*
+
+- Released versions will be in the format of `Major.Minor.Patch` where,
+as rule of thumb we will increase
+
+
+    MAJOR for incompatible API changes    
+    MINOR for new backwards-compatible functionality
+    PATCH for backwards-compatible bug fixes.
+
+- We'll keep the even/odd schema
+- Any new official release will be always even: 1.12.0, 1.14.0, 1.16.0,
+..., 1.124.0
+- A release will always be with a patch number (the last part) of `.0`.
+This ease OSGi deployments.
+- Diagnostic builds will be cut with the odd version and `-Rxxx` such as
+`1.15-R12345`.
+- In case of branching the increased part will always be the PATCH so:
+`1.16.0`, `1.16.1`, `1.16.2`, etc.
+- In case of branching the diagnostic build will follow the current
+pattern: `1.16.5-R12345`