Improve and document the release process (#266)

This change simplifies the process of updating of the module versions by consolidating them all to a single property. This follows the example given in the article [Maven CI Friendly Versions][1]. It also documents the steps for triggering a release version and advancing the snapshot version. Jira: INGEST-2133 [1]: https://maven.apache.org/maven-ci-friendly.html
LiveRamp · May 11, 2020 · 3210765 · 3210765
1 parent c09a4da
commit 3210765
Show file tree

Hide file tree

Showing 9 changed files with 119 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -113,33 +113,26 @@ Finally, there is one overarching Databases class that serves as a collection fo
 
 ## Download
 
-You can either build jack from source or pull the latest snapshot from
-Sonatype:
+You can [find releases] on The Central Repository and [find snapshots] on
+[Sonatype OSSRH] (OSS Repository Hosting).
+
+To get snapshots, add the OSSRH snapshot repository.  See the [guide to using
+multiple repositories].
 
 ```xml
 <repository>
-  <id>sonatype-snapshots</id>
-  <url>http://oss.sonatype.org/content/repositories/snapshots</url>
-  <layout>default</layout>
-    <releases>
-      <enabled>false</enabled>
-    </releases>
-  <snapshots>
-    <enabled>true</enabled>
-    <updatePolicy>always</updatePolicy>
-  </snapshots>
+  <id>ossrh-snapshots</id>
+  <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
+  <releases>
+    <enabled>false</enabled>
+  </releases>
 </repository>
 ```
 
-Depend on the JAR like so:
-
-```xml
-<dependency>
-  <groupId>com.liveramp</groupId>
-  <artifactId>jack</artifactId>
-  <version>1.3.0</version>
-</dependency>
-```
+[find releases]: https://search.maven.org/search?q=g:com.liveramp%20a:jack-*
+[find snapshots]: https://oss.sonatype.org/#nexus-search;gav~com.liveramp~jack*~~~
+[guide to using multiple repositories]: https://maven.apache.org/guides/mini/guide-multiple-repositories.html
+[Sonatype OSSRH]: https://central.sonatype.org/pages/ossrh-guide.html
 
 ## License
 

diff --git a/docs/release_process.md b/docs/release_process.md
@@ -0,0 +1,97 @@
+# Release Process
+
+By convention the `master` branch is the active development branch.  The
+assumption is there is only one active line of development at any time, so
+`master` is also where releases are made.
+
+## Developing and Releasing a New Patch Version
+
+Prerequisite: The head of the `master` branch is ready to be released as a patch
+update.
+
+1. Take note of the current released version.
+
+   This example shows how to list tags as versions in descending order.
+
+   ```console
+   $ git tag --list --sort='-version:refname'
+   jack-1.0
+   1.5.0
+   1.4.2
+   1.4.1
+   1.4.0
+   1.3.0
+   1.2
+   ```
+
+2. Increment the patch value by 1 to get the next release version.
+
+   Using the example above, the current release is "1.5.0" and incrementing the
+   patch value gives "1.5.1".
+
+3. Create an annotated git tag using the next release version.
+
+   ```
+   $ git tag -a -m 'Release 1.5.1' 1.5.1
+   ```
+
+   By creating an annotated tag (rather than a lightweight tag), the repository
+   will contain a record of who tagged a release and when.
+
+4. Push the newly created tag to GitHub.
+
+   ```
+   $ git push origin refs/tags/1.5.1
+   Enumerating objects: 1, done.
+   Counting objects: 100% (1/1), done.
+   Writing objects: 100% (1/1), 164 bytes | 164.00 KiB/s, done.
+   Total 1 (delta 0), reused 0 (delta 0)
+   To github.com:LiveRamp/jack.git
+    * [new tag]           1.5.1 -> 1.5.1
+   ```
+
+## Advancing the Minor or Major Version
+
+As soon as it's decided that the next release will be a major or minor update,
+the snapshot version in the repository should be updated.  Although it's not
+required because snapshots are by definition unstable, it's nice to communicate
+this to users sooner rather than later.
+
+The bookkeeping in Maven for advancing the major or minor version is the same.
+
+1. Decide on the new `MAJOR`.`MINOR` version.
+
+   Minor updates should increment the existing minor value by one.  Major
+   updates should increment the existing major value by one and set the minor
+   version to 0.
+
+2. Update the `revision` property in `com.liveramp:jack`'s POM.  Be sure to
+   retain the `SNAPSHOT` qualifier.
+
+   This is an example diff after changing the minor version from 5 to 6.
+
+   ```
+   $ git diff pom.xml
+   diff --git a/pom.xml b/pom.xml
+   index c3f2aff2..d5f28ca4 100644
+   --- a/pom.xml
+   +++ b/pom.xml
+   @@ -37,7 +37,7 @@
+        <db.user>root</db.user>
+        <db.pass>""</db.pass>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+   -    <revision>1.5-SNAPSHOT</revision>
+   +    <revision>1.6-SNAPSHOT</revision>
+      </properties>
+
+      <scm>
+   ```
+
+## Releasing a New Major or Minor Version
+
+1. Verify that the `revision` property in `com.liveramp:jack` is consistent with
+   the planned release.  If it is not, update it according to the steps above
+   and commit those changes to `master` first.
+
+2. Follow the steps from *Developing and Releasing a New Patch Version*, but
+   skip to Step 3 and use the desired release version.
diff --git a/jack-core/pom.xml b/jack-core/pom.xml
@@ -3,12 +3,11 @@
   <modelVersion>4.0.0</modelVersion>
 
   <artifactId>jack-core</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
 
   <parent>
     <groupId>com.liveramp</groupId>
     <artifactId>jack</artifactId>
-    <version>1.7.0-SNAPSHOT</version>
+    <version>${revision}</version>
   </parent>
 
   <properties>

diff --git a/jack-mysql/pom.xml b/jack-mysql/pom.xml
@@ -3,12 +3,11 @@
   <modelVersion>4.0.0</modelVersion>
 
   <artifactId>jack-mysql</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
 
   <parent>
     <groupId>com.liveramp</groupId>
     <artifactId>jack</artifactId>
-    <version>1.7.0-SNAPSHOT</version>
+    <version>${revision}</version>
   </parent>
 
   <properties>

diff --git a/jack-postgresql/pom.xml b/jack-postgresql/pom.xml
@@ -3,12 +3,11 @@
   <modelVersion>4.0.0</modelVersion>
 
   <artifactId>jack-postgresql</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
 
   <parent>
     <groupId>com.liveramp</groupId>
     <artifactId>jack</artifactId>
-    <version>1.7.0-SNAPSHOT</version>
+    <version>${revision}</version>
   </parent>
 
   <properties>

diff --git a/jack-redshift/pom.xml b/jack-redshift/pom.xml
@@ -3,12 +3,11 @@
   <modelVersion>4.0.0</modelVersion>
 
   <artifactId>jack-redshift</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
 
   <parent>
     <groupId>com.liveramp</groupId>
     <artifactId>jack</artifactId>
-    <version>1.7.0-SNAPSHOT</version>
+    <version>${revision}</version>
   </parent>
 
   <properties>

diff --git a/jack-store/pom.xml b/jack-store/pom.xml
@@ -3,12 +3,11 @@
   <modelVersion>4.0.0</modelVersion>
 
   <artifactId>jack-store</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
 
   <parent>
     <groupId>com.liveramp</groupId>
     <artifactId>jack</artifactId>
-    <version>1.7.0-SNAPSHOT</version>
+    <version>${revision}</version>
   </parent>
 
   <properties>

diff --git a/jack-test/pom.xml b/jack-test/pom.xml
@@ -3,12 +3,11 @@
   <modelVersion>4.0.0</modelVersion>
 
   <artifactId>jack-test</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
 
   <parent>
     <groupId>com.liveramp</groupId>
     <artifactId>jack</artifactId>
-    <version>1.7.0-SNAPSHOT</version>
+    <version>${revision}</version>
   </parent>
 
   <properties>

diff --git a/pom.xml b/pom.xml
@@ -4,7 +4,7 @@
 
   <groupId>com.liveramp</groupId>
   <artifactId>jack</artifactId>
-  <version>1.7.0-SNAPSHOT</version>
+  <version>${revision}</version>
   <packaging>pom</packaging>
 
   <name>Jack</name>
@@ -37,6 +37,7 @@
     <db.user>root</db.user>
     <db.pass>""</db.pass>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <revision>1.7-SNAPSHOT</revision>
   </properties>
 
   <scm>