simantics/platform and simantics/third-party Git repositories have a branch release/x.y.z[.w] and tag x.y.z[.w].release/x.y.z[.w] and tag called x.y.z[.w].release/x.y.z[.w] release stabilisation branchThere are both plug-in components and products that are part of the Simantics Release Train that shall be released simultaneously to a major or minor Simantics release.
+Plug-in components are installable features that are deployed online as P2 repositories for general availability. Products are deployed as ZIP files and made available online in designated locations on simantics.org.
+Core components of the release train:
Plug-in components that are part of the release train:
+Products that are part of the release train:
+In the following sections each task is described step by step.
+For simplicity, each of these components are versioned accoring to platform versioning, i.e. for Platform SDK 1.26.0 there will be Simantics Desktop 1.26.0, Sysdyn 1.26.0, and so on.
+Ensure that Gitlab has a release engineering issue for the branched release, +such as Simantics 1.34.0 release engineering
+$version release engineering.simantics/platform#16.releng and $version to the new issueWhen release stabilisation starts, branch simantics/platform and simantics/third-party repositories:
git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git
-cd platform
-git branch release/x.y.z[.w] <commit>
-git push origin release/x.y.z[.w]
-
-git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git
-cd third-party
-git branch release/x.y.z[.w] <commit>
-git push origin release/x.y.z[.w]
-When creating major/minor releases <commit> is usually a commit in the master branch.
+
When release stabilisation starts, all relevant repositories need to be branched.
+When creating major/minor releases <commit> is usually a commit in the master branch.
With service releases, branch from an existing release/* branch instead.
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]
+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
-Edit all target platform files in releng/org.simantics.sdk.build.targetdefinition/, i.e.
simantics.targetorg.simantics.sdk.build.targetdefinition.targetorg.simantics.sdk.build.targetdefinition-semantum.targetAt the beginning of each .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">
+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
-Next, replace the following rows in those 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"/>
+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
-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"/>
+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 or in review 1362.
+The changes include:
release/x.y.z[.w]truePerform and push the changes in master by running:
+branch=master
+./release-helper.sh $version $branch $user checkout
+./release-helper.sh $version $branch $user bump-master-version x.y.z X.Y.Z
+./release-helper.sh $version $branch $user push
+x.y.z is the old version number of master and X.Y.Z is the new version number.
+Trigger an execution of the simantics-release-train Jenkins job with parameters
release/x.y.z[.w]truerelease/x.y.z[.w]trueto 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.
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
+ }
+}
+Documentation to review:
For each wiki page:
When the release branches are ready for the release, tag them with the tag vx.y.z[.w]:
git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git
-cd platform
-git checkout release/x.y.z[.w]
-git tag vx.y.z[.w] -m "Simantics x.y.z[.w] release"
-git push origin --tags
-
-git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git
-cd third-party
-git checkout release/x.y.z[.w]
-git tag vx.y.z[.w] -m "Simantics x.y.z[.w] release"
-git push origin --tags
+./release-helper.sh x.y.z release/x.y.z your-git-username checkout
+./release-helper.sh x.y.z release/x.y.z your-git-username pull
+./release-helper.sh x.y.z release/x.y.z your-git-username tag
+./release-helper.sh x.y.z release/x.y.z your-git-username push-tags
-Note The -m argument must be supplied to create an annotated tag.
+
Note: release-helper.sh will supply the -m argument to git tag to create an annotated tag.
Only annotated or signed tags can be pushed to Gerrit.
-Dump documentation wikis
-Dump documentation wiki using dump-wikis.sh script.
-The wiki documentation is mainly in MediaWiki installations. The only
-sane way to tag the documentation is to back up the mysql database
-backing the wiki.
+Backup documentation wiki databases
+NOTE: This step is now deprecated since we are in the process of moving all mediawiki-based documentation into the platform git repository.
+This step is only necessary for major/minor releases, not for service releases.
+The wiki databases to be backed up are:
+
+These are MediaWiki installations. The only sane way to "tag" the documentation
+is to back up the mysql database backing the wiki. Should the wiki be required
+at a later time for some reason, we'll put the documentation up then in a
+separate Mediawiki installation.
+
+- Dump documentation wiki databases using dump-wikis.sh script.
+- Put the generated backup x.y.z.tar.gz at /var/backup/simantics-releases/x.y.z/wiki/
+
Compile change log entry
- Edit the main page and add a a link for release x.y.z[.w].
@@ -494,14 +585,15 @@ backing the wiki.
Disseminate information about the release
-- Redmine: Post news on the developer/user-visible changes here.
+- Developer Wiki: Update roadmap at http://dev.simantics.org/index.php/Roadmap
+- Redmine: Post news on the developer/user-visible changes here
- simantics.org: Post news on the release and a link to the redmine post
-- dev wiki: Update roadmap at http://dev.simantics.org/index.php/Roadmap
-- simantics-developers@simantics.org Send mail to simantics-developers:
+- Members Wiki: Update frame plan to reflect the realized dates and link to Redmine news
+- mailto:simantics-developers@simantics.org Send "newsletter" to `simantics-developers@simantics.org:
-Mail template:
+Newsletter template:
Hello everyone,
-
+
Simantics release x.y.z[.w] has been released. Head over to
https://www.simantics.org/redmine/news/<news number>
for the release news.
@@ -509,9 +601,11 @@ for the release news.
Best regards,
Simantics Release Engineering Team
-News entry template:
-On <date> Simantics x.y.z[.w] was tagged in SVN. Please find change log at:
-* [[simantics-platform:Simantics_xyzw|Simantics x.y.z.w]]
+Redmine news template:
+Title: Simantics x.y.z[.w] released
+
+Simantics x.y.z[.w] was released on <date>.
+Please find change log at: [[simantics-platform:Simantics_xyzw|Simantics x.y.z[.w]]]
Insert some general thoughts on the release...
@@ -519,8 +613,6 @@ Insert some general thoughts on the release...
TODO
- Incorporate tutorial code in the platform repository as a separate folder to allow platform builds to directly ensure that the tutorial code still builds OK
-- Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release in one go
-- Start using https://github.com/mbarbero/fr.obeo.releng.targetplatform to generate
.target files. .tpd files allow specifying version ranges instead of specific versions.