Rm-3196: release workflow

jann0k · jann0k · commit 267f85213d1e · 2024-05-29T18:15:02.000+03:00
diff --git a/README.md b/README.md
@@ -202,32 +202,14 @@ service haveged start
 
 See `cdoc2-cli/README.md`
 
-## Releasing
+## Releasing and version management
 
-First update CHANGELOG.md - follow semantic versioning
+See [VERSIONING.md](VERSIONING.md)
 
-Will update version numbers in pom.xml files and create tag with version v{x.y.z} in git
 
-# Non-Interactive mode without pushing changes (for release simulation)
-```
-mvn release:clean
-mvn --batch-mode -Dtag=v{x.y.z} release:prepare -DreleaseVersion={x.y.z} -DdevelopmentVersion={x.y+1.z}-SNAPSHOT -DdryRun=true -DpushChanges=false
-mvn release:perform -Darguments="-Dmaven.deploy.skip=true"
-```
-
-# Non-Interactive mode
-```
-mvn release:clean
-mvn --batch-mode -Dtag=v{x.y.z} release:prepare -DreleaseVersion={x.y.z} -DdevelopmentVersion={x.y+1.z}-SNAPSHOT -DdeveloperConnectionUrl=scm:git:${git.repo.url}"
-mvn release:perform -Darguments="-Dmaven.deploy.skip=true"
-```
 
-Verify that git repositories are synced (master points to same commit) and the tag is pushed (using `git push <remote> v{x.y.z}`).
 
-As maven repository doesn't exist yet, then maven deploy is not performed
 
-For more info, see
-[Maven Non-interactive Release](https://maven.apache.org/maven-release/maven-release-plugin/examples/non-interactive-release.html)
 
 
 
diff --git a/VERSIONING.md b/VERSIONING.md
@@ -0,0 +1,91 @@
+# Versioning guidelines for CDOC2 project
+
+CDOC2 modules are split between two repositories (or more in future). As all modules are not in the
+same repository, then version management becomes necessity.
+
+To help with version management, this document describes some ways to manage module versions.
+
+CDOC2 project tries to follow [semantic versioning](https://semver.org/)
+
+## Development without release (inc_version.sh)
+
+* Create feature branch <TASK_ID>_<short_description>
+* Make changes
+
+Before opening merge request, run `inc_versions.sh -d` (dry-run) and `inc_versions.sh`
+
+This, will scan modules and increase module version only for changed modules that are not already on
+"-SNAPSHOT" version. Changes are detected only for current branch and won't work for main branch.
+
+* `git diff` to verify changes
+* Commit, push
+* Create MR
+
+`inc_version.sh -d` will print out changed modules, but doesn't change any files.
+
+The script is not perfect, for example if you only change README in a module, then module is still
+considered changed although no code changes.
+
+## Using latest version of modules (use_latest_snapshot.sh)
+
+After creating new version Maven module or artifact, install it locally
+
+`mvn install`
+`mvn -f <module_name> install`
+
+### Update cdoc2 dependencies for single module
+
+* `mvn -f <module> versions:use-latest-versions -Dincludes=ee.cyber.cdoc2:* -DexcludeReactor=false -DallowSnapshots=true`
+
+Example: `mvn -f cdoc2-server/get-server versions:use-latest-versions -Dincludes=ee.cyber.cdoc2:* -DexcludeReactor=false -DallowSnapshots=true`
+
+
+### Update cdoc2 dependencies for all modules in repository
+
+* Run `use_latest_snapshot.sh` to update all modules
+* `git diff` to verify changes
+
+## Releases (prepare_release.sh and make_release.sh)
+
+General release procedure:
+
+* Checkout clean branch (usually 'master')
+* `prepare_release.sh` (changes versions to RELEASE versions and runs tests)
+* Verify changes (`git diff`)
+* Edit CHANGELOG.md
+* `make_release.sh` (`git commit; git push` RELEASE branch and `mvn deploy` RELEASE artifacts)
+
+This will change -SNAPSHOT version to release version, update dependencies in all modules to latest
+non-SNAPSHOT version. Build, test, create release branch, push changes, deploy maven artifacts.
+
+Without parameters `prepare_release.sh` will use version (with -SNAPSHOT removed) from parent pom. 
+To specify custom release version use `-v`, example `prepare_release.sh -v 1.2.3`. This will update
+version in parent pom before changing other versions.
+
+If everything went well, then
+* release branch was created with name 'release_v<parent-pom.version>'
+* Maven artifacts with release version are in Maven repository
+* original branch is checked out ('master' usually)
+
+To finish create squash merge from release branch to main branch
+```bash
+git merge --squash $RELEASE_BRANCH
+git commit -m "Squashed commit from $RELEASE_BRANCH"
+git push $GIT_REMOTE $GIT_BRANCH
+```
+
+### Release cdoc2-java-ref-impl and cdoc2-capsule-server
+
+Since test code for cdoc2-capsule-server depends on cdoc2-java-ref-impl `cdoc2-lib` module and
+transiently `cdoc2-client` module, then for bigger releases following procedure is recommended:
+
+* Checkout both repositories
+* Run `prepare_release.sh` in `cdoc2-java-ref-impl` and then in `cdoc2-capsule-server`. That installs
+  `cdoc2-lib` into local maven repository and `cdoc2-capsule-server` will use it during testing
+  ('mvn verify')
+* Update CHANGELOGs in both repositories
+* Run `make_release.sh` in `cdoc2-java-ref-impl` and then in `cdoc2-capsule-server`
+
+### make_release.sh without deploy
+
+`make_release.sh -d` will create release branch, but will not deploy Maven artifacts. 
diff --git a/cdoc2-client/pom.xml b/cdoc2-client/pom.xml
@@ -1,9 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <artifactId>cdoc2</artifactId>
+        <groupId>ee.cyber.cdoc2</groupId>
+        <version>1.3.0-SNAPSHOT</version>
+    </parent>
 
     <artifactId>cdoc2-client</artifactId>
-    <groupId>ee.cyber.cdoc2</groupId>
     <version>1.3.0-SNAPSHOT</version>
     <description>CDOC2 server client generation from openapi specification</description>
 
diff --git a/inc_versions.sh b/inc_versions.sh
@@ -0,0 +1,91 @@
+#!/bin/bash
+
+# Increase maven module version for changed modules based on git diff.
+
+# Based on
+# https://gist.github.com/corneil/20585cb944615abb434063b8507d2d8d
+
+
+function itemInModules() {
+  local e
+  for e in ${MODULES}; do
+    if [[ "$e" == "$ITEM" ]]; then
+      echo "1"
+      return 0
+    fi
+  done
+  echo "0"
+}
+function addItem() {
+    if [ "$MODULES" == "" ]; then
+      echo "$1"
+    else
+      echo "$MODULES $1"
+    fi
+}
+
+PERFORM=true
+
+while getopts ":d" opt; do
+  case ${opt} in
+    d)
+      echo "-d Dry-run mode"
+      PERFORM=false
+      ;;
+    ?)
+      echo "Invalid option: -${OPTARG}."
+      exit 1
+      ;;
+  esac
+done
+
+# Find parent branch
+#https://gist.github.com/joechrysler/6073741
+#https://stackoverflow.com/questions/3161204/how-to-find-the-nearest-parent-of-a-git-branch?noredirect=1&lq=1
+PARENT_BRANCH=$(git show-branch -a \
+                | grep '\*' \
+                | grep -v "$(git rev-parse --abbrev-ref HEAD)" \
+                | head -n1 \
+                | sed 's/.*\[\(.*\)\].*/\1/' \
+                | sed 's/[\^~].*//')
+echo
+echo "Using $PARENT_BRANCH as parent branch"
+echo
+
+
+MODIFIED=$(git diff --name-only "$PARENT_BRANCH")
+ALL_MODULES=$(find . -name "pom.xml" -type f -exec dirname '{}' \; | sed 's/\.\///' | sort -r)
+MODULES=
+for file in $MODIFIED; do
+  #FILE=$(realpath $file)
+  echo "$file was changed"
+  for ITEM in $ALL_MODULES; do
+    if [[ "$ITEM" != "." ]] && [[ "$file" == *"$ITEM"* ]]; then
+      echo "Matched $ITEM"
+      HAS_ITEM=$(itemInModules)
+      if ((HAS_ITEM == 0)); then
+        MODULES=$(addItem "$ITEM")
+      fi
+      break
+    fi
+  done
+done
+
+#echo "All modules: $ALL_MODULES"
+echo
+echo "Changed modules: $MODULES"
+echo
+for module in $MODULES; do
+
+  if [[ "$PERFORM" = true ]]; then
+    MODULE_VERSION=$(mvn -f "$module" help:evaluate -Dexpression=project.version -q -DforceStdout)
+    if [[ ${MODULE_VERSION} == *"SNAPSHOT"* ]];then
+        echo "Ignoring $module as it already on SNAPSHOT "
+    else
+        echo "Creating -SNAPSHOT minor version for $module;"
+        mvn -f "$module" versions:set -DnextSnapshot -DnextSnapshotIndexToIncrement=2
+    fi
+  else
+    echo "Dry-run. Not increasing version for $module."
+  fi
+done
diff --git a/make_release.sh b/make_release.sh
@@ -0,0 +1,83 @@
+#!/bin/bash
+
+set -o xtrace
+# git commit
+# git tag
+# git push
+# mvn deploy
+# docker deploy
+
+
+CDOC2_VER=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
+
+GIT_BRANCH=$(git branch --show-current)
+GIT_REMOTE=$(git config --get-regexp "branch\.$GIT_BRANCH\.remote" | sed -e "s/^.* //")
+
+# if mvn deploy is called
+DEPLOY=true
+
+if [[ "master" != "$GIT_BRANCH" ]]; then
+  echo "Not on 'master' branch. You have 5 seconds to abort or the script will continue"
+  sleep 5
+fi
+
+if [[ ${CDOC2_VER} == *"SNAPSHOT"* ]];then
+    echo "cdoc2 is still on SNAPSHOT ${CDOC2_VER}. Did you run prepare_release.sh?"
+    exit 2
+fi
+
+if ! grep -q ${CDOC2_VER} "CHANGELOG.md"; then
+  echo "Can't find \"${CDOC2_VER}\" in CHANGELOG.md. Did you write CHANGELOG?"
+  exit 3
+fi
+
+while getopts ":d" opt; do
+  case ${opt} in
+    d)
+      echo "-d Dry-run mode. Deploy will not be performed."
+      DEPLOY=false
+      ;;
+    ?)
+      echo "Invalid option: -${OPTARG}."
+      exit 1
+      ;;
+  esac
+done
+
+
+
+export RELEASE_BRANCH="release_v$CDOC2_VER"
+export RELEASE_TAG="v$CDOC2_VER"
+
+git checkout -b "$RELEASE_BRANCH" || exit 1
+git commit -a -m "Release cdoc2-java-ref-impl version $CDOC2_VER" || exit 1
+git push "$GIT_REMOTE" -u "$RELEASE_BRANCH" || exit 1
+git tag "$RELEASE_TAG" || exit 1
+git push --tags $GIT_REMOTE "$RELEASE_TAG" || exit 1
+echo "Created release branch $RELEASE_BRANCH"
+
+# to delete branch, run:
+# git checkout parent_branch
+# git branch -D test_v1.2.0
+# git push gitlab.ext -d test_v1.2.0
+
+
+#deploy RELEASE modules
+if [[ "$DEPLOY" = true ]]; then
+  mvn deploy -DskipTests
+  if [[ $? -ne 0 ]]; then
+    echo "mvn deploy failed. If this was temporary error, it may be possible to recover by re-running 'mvn deploy -DskipTests'"
+  fi
+else
+  echo "DEPLOY=$DEPLOY. To deploy Maven artifacts, run 'mvn deploy -DskipTests' on branch $RELEASE_BRANCH"
+fi
+
+
+# switch back to original branch
+git checkout $GIT_BRANCH
+
+echo "Created release branch $RELEASE_BRANCH"
+echo "To merge squash back to your branch. Run"
+echo "git merge --squash $RELEASE_BRANCH"
+echo "git commit -m \"Squashed commit from $RELEASE_BRANCH\""
+echo "git push $GIT_REMOTE $GIT_BRANCH"
diff --git a/prepare_release.sh b/prepare_release.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+
+GIT_BRANCH=$(git branch --show-current)
+
+if [[ "master" != "$GIT_BRANCH" ]]; then
+  echo "Not on 'master' branch. You have 5 seconds to abort, before script will continue"
+  sleep 5
+fi
+
+
+#if [[ -n $(git cherry -v) ]]; then
+#  echo "Detected unpushed commits. Exit"
+#  exit 1
+#fi
+#
+#if [[ -n $(git status --porcelain --untracked-files=no) ]]; then
+#  echo "Uncommited changes detected. Exit"
+#  exit 1
+#fi
+
+while getopts "v:" opt; do
+  case $opt in
+    v)
+      echo "Changing parent pom version to: $OPTARG" >&2
+      mvn versions:set -DnewVersion="${OPTARG}" -DupdateMatchingVersions=false
+      ;;
+    ?)
+      echo "Invalid option: -${OPTARG}."
+      exit 1
+      ;;
+  esac
+done
+
+
+# replace module -SNAPSHOT version with release version (non-SNAPSHOT)
+mvn versions:set -DremoveSnapshot
+# build and install into local maven package repository
+mvn install
diff --git a/use_latest_snapshot.sh b/use_latest_snapshot.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+#Update dependencies for latest -SNAPSHOT
+
+mvn versions:use-latest-versions -Dincludes=ee.cyber.cdoc2:* -DexcludeReactor=false -DallowSnapshots=true
