-## Prepare release branch for use
-
-### Prepare .target files
-
-1. Retrieve release branch of the platform repository
-
- git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git
- cd platform
- git branch release/x.y.z[.w] remotes/origin/release/x.y.z[.w]
- git checkout release/x.y.z[.w]
-
-2. Edit all target platform files in `releng/org.simantics.sdk.build.targetdefinition/`, i.e.
- * `simantics.target`
- * `org.simantics.sdk.build.targetdefinition.target`
-
- At the beginning of simantics.target file, increment `sequenceNumber` by 1
- ~~~
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
- <?pde version="3.8"?>
- <target name="Simantics x.y.z[.w]" sequenceNumber="11">
- ~~~
-
- Next, replace the following rows in both mentioned files:
-
- ~~~
- <repository location="http://www.simantics.org/download/master/sdk"/>
- <repository location="http://www.simantics.org/download/master/external-components/maven"/>
- <repository location="http://www.simantics.org/download/master/external-components/manual"/>
- ~~~
-
- with
-
- ~~~
- <repository location="http://www.simantics.org/download/release/x.y.z[.w]/sdk"/>
- <repository location="http://www.simantics.org/download/release/x.y.z[.w]/external-components/maven"/>
- <repository location="http://www.simantics.org/download/release/x.y.z[.w]/external-components/manual"/>
- ~~~
-
-### Initialize release branch distribution web site
-
-* Run [SDK/Deploy External Components to Web](https://www.simantics.org/jenkins/job/SDK/job/Deploy%20External%20Components%20to%20Web/) build with parameters:
- * **GERRIT_REFNAME:** `release/x.y.z[.w]`
- * **PUBLISH_ARTIFACTS:** `true`
-* Run the [SDK/Simantics SDK](https://www.simantics.org/jenkins/job/SDK/job/Simantics%20SDK/) build with parameters:
- * **GERRIT_REFNAME:** `release/x.y.z[.w]`
- * **PUBLISH_ARTIFACTS:** `true`
-
-Running these two builds will ensure that both the external components required to build the SDK and the Simantics SDK for the new release branch are published online at `http://www.simantics.org/download/release/x.y.z[.w]/`.
-
-After this, whenever changes are pushed/merged to `release/x.y.z[.w]` branch in Gerrit, new **SDK/Simantics SDK** builds are triggered automatically and they will publish the results at the same location online.
-
-This means that one does not have to do any tricks after this to build and publish the SDK as a P2 repository online. It is an automated process that is performed by the [SDK/Simantics SDK](https://www.simantics.org/jenkins/job/SDK/job/Simantics%20SDK/) Jenkins job.
+Instead of doing this clone+branch+push sequence for every SDK repository separately, please use the included `release-helper.sh` shell script to perform this mechanical work.
+The script supports many useful basic git commands which all perform the requested operation on all the release train repositories.
+The operations can be seen from the help text printed by the script when given no arguments:
+
+```
+Usage: release-helper.sh <version> <branch-name> <user-name> <command> [<command-arguments>]
+
+Commands:
+ clone The first thing that needs to be done before anything else
+ Clones all platform repositories under directory <version>
+
+Inspection commands:
+ diff [args] Run git diff [args] for each platform repository
+ log [args] Run git log [args] for each platform repository
+ status [args] Run git status [args] for each platform repository
+ list-tags Run git tag -l for each repository
+
+Action:
+ add
+ branch Run git branch <branch-name> for each platform repository
+ checkout Run git checkout <branch-name> for each repository
+ commit
+ fetch Run git fetch --all for each repository
+ pull Run git pull --all for each repository
+ push Run git push origin <branch> for each repository
+ push-tags Run git push --tags for each repository
+ remove-tag Run git tag -d v<branch> for each repository
+ reset [args] Run git reset [args] for each repository
+ tag Run git checkout <branch> and
+ git tag -a v<branch> -m "Simantics <branch> simultaneous release"
+ for each repository
+
+Compound release commands:
+ prepare-release-branch <from-branch>
+ <from-branch> the name of the branch that the codebase is currently on
+
+Top-level release commands:
+ bump-master-version <from-version> <to-version>
+ <from-version> the version string to replace
+ <to-version> the replacing new version string
+
+ branch-release <from-branch>
+ <from-branch> the branch to create the service branch from
+ e.g. master or release/x.y.z
+```
+
+Begin by cloning all the repositories for working on
+
+ user=<your-git-username>
+ version=x.y.z
+ branch=release/x.y.z
+ ./release-helper.sh $version $branch $user clone
+
+This will create a directory called `x.y.z` under the current working directory and clone all the repositories under it.
+The first `version` argument is only used for the base working directory `x.y.z`.
+The second `branch` argument tells what branch to specify to some of the available actions, e.g. `branch`, `checkout`, etc.
+
+Creating the release branch from master and pushing the new branches to remote happens as follows:
+
+ # When the commit messages appear, add references to created
+ # Gitlab release engineering issues by adding this to the commit message:
+ #
+ # gitlab #xxxx
+ #
+ # where xxxx is the release engineering issue for the respective project
+ ./release-helper.sh $version $branch $user branch-release master
+ ./release-helper.sh $version $branch $user push
+
+If you're creating a service release `x.y.w` from `x.y.z` where `w > z`, do this:
+
+ fromBranch=release/x.y.z
+ branch=release/x.y.w
+ ./release-helper.sh $version $branch $user branch-release $fromBranch
+ ./release-helper.sh $version $branch $user push
+
+If you branched a new release from `master`, you should also bump the revision of the master branch right now to start the next release cycle in master.
+An example of these changes can be seen in [gitweb](https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=commit;h=564ac84a2949b19ce5c1c7c838b575527ec42b09) or in [review 1362](https://gerrit.simantics.org/r/#/c/1362).
+The changes include:
+ * Simantics Desktop splash screen update (version number)
+ * Simantics target platform name to state correct development version
+ * org.simantics.sdk feature version bump
+ * org.simantics.sdk.repository project version bump
+
+Perform and push the changes by running:
+
+ ./release-helper.sh $version $branch $user bump-master-version 1.35.0 1.36.0
+ ./release-helper.sh $version $branch $user push
+
+### Test Release Train build
+
+Trigger an execution of the [simantics-release-train](https://www.simantics.org/jenkins/job/simantics-release-train/) Jenkins job with parameters
+* GERRIT_REFNAME: `release/x.y.z[.w]`
+* PUBLISH_ARTIFACTS: `true`
+
+to ensure that all components of the release train build fine and to publish first versions of P2 repositories of everything online.
+
+The release train build is currently never ran automatically.
+However, after following all these steps, whenever changes are pushed/merged to `release/x.y.z[.w]` branch in Gerrit, new Jenkins builds are triggered automatically and they will publish the results (P2 repositories/products) at their designated locations online.
+
+#### [Optional reading] Release train build details
+
+The release train build does two very important steps as the first things,
+i.e. build the external dependency P2 repositories for both the
+Platform SDK and Simupedia:
+~~~
+stage('External Dependencies') {
+ node {
+ build job: 'SDK/Deploy External Components to Web', parameters: params1
+ build job: 'Member Components/Simupedia/fi.semantum.simupedia.build.p2.site', parameters: params1
+ }
+}
+~~~
+After that it builds the Platform SDK and Simupedia before building anything else:
+~~~
+stage('SDK') {
+ node {
+ build job: 'SDK/Simantics SDK', parameters: params1
+ // Note that Simantics SDK builds simupedia-git as well
+ }
+}
+~~~