<body>\r
<h1>Definition of Done for Simantics Platform Releases</h1>\r
<ol>\r
-<li>The <code>simantics/platform</code> and <code>simantics/third-party</code> Git repositories have a branch <code>release/x.y.z[.w]</code> and tag <code>x.y.z[.w]</code>.</li>\r
+<li>All Git repositories that are part of the Simantics release train have a branch called <code>release/x.y.z[.w]</code> and tag called <code>x.y.z[.w]</code>.</li>\r
<li><a href="https://www.simantics.org/redmine/projects/simantics-platform/wiki/ChangeLog">A change log entry</a> is compiled from the issues in this release and made available to the general public separately for the platform and for the open products included in the release train.</li>\r
<li><a href="http://dev.simantics.org/index.php/Roadmap">Roadmap</a> is up-to-date.</li>\r
<li><a href="http://dev.simantics.org/index.php/Tutorials">Tutorials</a> are up-to-date and coherent with the platform.</li>\r
</ul>\r
<hr />\r
<h1>Released Plug-in Components and Products</h1>\r
-<p>There 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.</p>\r
+<p>There are both plug-in components and products that are part of the <em>Simantics Release Train</em> that shall be released simultaneously to a major or minor Simantics release.</p>\r
<p>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.</p>\r
-<p>Products that are part of the release train:</p>\r
+<p>Core components of the release train:</p>\r
<ul>\r
-<li>Simantics Desktop</li>\r
-<li>Simantics System Dynamics Tool - <a href="https://www.simantics.org:8088/r/gitweb?p=simantics/sysdyn.git;a=summary">simantics/sysdyn.git</a></li>\r
+<li>External third party library dependencies required by the platform - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/third-party.git;a=summary">simantics/third-party.git</a></li>\r
+<li>The Simantics Platform - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/platform.git;a=summary">simantics/platform.git</a></li>\r
</ul>\r
<p>Plug-in components that are part of the release train:</p>\r
<ul>\r
-<li>Simantics R - <a href="https://www.simantics.org:8088/r/gitweb?p=simantics/r.git;a=summary">simantics/r.git</a></li>\r
-<li>FMIL - <a href="https://www.simantics.org:8088/r/gitweb?p=simantics/fmil.git;a=summary">simantics/fmil.git</a></li>\r
-<li>FMI Studio - <a href="https://www.simantics.org:8088/r/gitweb?p=members/fmi.git;a=summary">members/fmi.git</a></li>\r
-<li>Simupedia - <a href="https://www.simantics.org/svn/members/simupedia">Members SVN</a></li>\r
+<li>Simupedia - <a href="https://gerrit.simantics.org/r/gitweb?p=members/simupedia.git;a=summary">members/simupedia.git</a></li>\r
+<li>FMIL - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/fmil.git;a=summary">simantics/fmil.git</a></li>\r
+<li>FMI Studio - <a href="https://gerrit.simantics.org/r/gitweb?p=members/fmi.git;a=summary">members/fmi.git</a></li>\r
+<li>Interoperability components - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/interop.git;a=summary">simantics/interop.git</a></li>\r
+<li>Simantics R binding - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/r.git;a=summary">simantics/r.git</a></li>\r
+<li>Matlab SCL binding - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/matlab.git;a=summary">simantics/matlab.git</a></li>\r
+<li>Python SCL binding - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/python.git;a=summary">simantics/python.git</a></li>\r
+<li>Simantics System Dynamics - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/sysdyn.git;a=summary">simantics/sysdyn.git</a></li>\r
+<li>Simantics District modelling components - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/district.git;a=summary">simantics/district.git</a></li>\r
+<li>Simantics 3D modelling components - <a href="https://gerrit.simantics.org/r/gitweb?p=simantics/3d.git;a=summary">simantics/3d.git</a></li>\r
+<li>Simantics Proteus toolset - <a href="https://gerrit.simantics.org/r/gitweb?p=gold-members/proteus.git;a=summary">gold-members/proteus.git</a></li>\r
+</ul>\r
+<p>Products that are part of the release train:</p>\r
+<ul>\r
+<li>Simantics Desktop</li>\r
+<li>Simantics System Dynamics Tool\r
+<ul>\r
+<li>This is Simantics Desktop with Simantics System Dynamics Tool features installed</li>\r
+</ul>\r
+</li>\r
</ul>\r
<p>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.</p>\r
<hr />\r
</ul>\r
<hr />\r
<h1>Simantics Platform Release - Step by Step</h1>\r
-<h2>Create release branch from selected commit</h2>\r
-<p>When release stabilisation starts, branch <code>simantics/platform</code> and <code>simantics/third-party</code> repositories:</p>\r
-<pre><code>git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
-cd platform\r
-git branch release/x.y.z[.w] <commit>\r
-git push origin release/x.y.z[.w]\r
-\r
-git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git\r
-cd third-party\r
-git branch release/x.y.z[.w] <commit>\r
-git push origin release/x.y.z[.w]\r
-</code></pre>\r
-<p>When creating major/minor releases <code><commit></code> is usually a commit in the <code>master</code> branch.\r
-With service releases, branch from an existing <code>release/*</code> branch instead.</p>\r
-<h2>Prepare release branch for use</h2>\r
-<h3>Prepare .target files</h3>\r
-<ol>\r
-<li>\r
-<p>Retrieve release branch of the platform repository</p>\r
-<pre><code>git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
-cd platform\r
-git branch release/x.y.z[.w] remotes/origin/release/x.y.z[.w]\r
-git checkout release/x.y.z[.w]\r
-</code></pre>\r
-</li>\r
-<li>\r
-<p>Edit all target platform files in <code>releng/org.simantics.sdk.build.targetdefinition/</code>, i.e.</p>\r
+<h2>Create release engineering issue(s) in Gitlab</h2>\r
+<p>Ensure that Gitlab has a release engineering issue for the branched release,\r
+such as <a href="https://gitlab.simantics.org/simantics/platform/issues/16">Simantics 1.34.0 release engineering</a></p>\r
<ul>\r
-<li><code>simantics.target</code></li>\r
-<li><code>org.simantics.sdk.build.targetdefinition.target</code></li>\r
+<li>Make a new release issue with title <code>$version release engineering</code>.</li>\r
+<li>Add a link to the previous previous release's issue in the new issue description, e.g. <code>simantics/platform#16</code>.</li>\r
+<li>Add labels <code>releng</code> and <code>$version</code> to the new issue</li>\r
</ul>\r
-<p>At the beginning of simantics.target file, increment <code>sequenceNumber</code> by 1 and replace\r
-the version numbers in target name and <code>org.simantics.sdk.feature.group</code> and\r
-<code>org.simantics.sdk.source.feature.group</code> with <code>x.y.z[.w]</code>:</p>\r
-<pre><code><?xml version="1.0" encoding="UTF-8" standalone="no"?>\r
-<?pde version="3.8"?>\r
-<target name="Simantics x.y.z[.w]" sequenceNumber="11">\r
-<unit id="org.simantics.sdk.feature.group" version="x.y.z[.w]"/>\r
-<unit id="org.simantics.sdk.source.feature.group" version="x.y.z[.w]"/>\r
-</code></pre>\r
-<p>Next, replace the following rows in both mentioned files:</p>\r
-<pre><code><repository location="http://www.simantics.org/download/master/sdk"/>\r
-<repository location="http://www.simantics.org/download/master/external-components/maven"/>\r
-<repository location="http://www.simantics.org/download/master/external-components/manual"/>\r
-</code></pre>\r
-<p>with</p>\r
-<pre><code><repository location="http://www.simantics.org/download/release/x.y.z[.w]/sdk"/>\r
-<repository location="http://www.simantics.org/download/release/x.y.z[.w]/external-components/maven"/>\r
-<repository location="http://www.simantics.org/download/release/x.y.z[.w]/external-components/manual"/>\r
-</code></pre>\r
-</li>\r
-<li>\r
-<p>Edit version number of <code>org.simantics.sdk</code> feature in <code>features/org.simantics.sdk.feature/feature.xml</code> to <code>x.y.z[.w]</code>.</p>\r
-<pre><code><feature\r
- id="org.simantics.sdk"\r
- label="Simantics SDK"\r
- version="x.y.z"\r
- provider-name="VTT Technical Research Centre of Finland">\r
-</code></pre>\r
-<p>An example of these changes can be seen in <a href="https://www.simantics.org:8088/r/gitweb?p=simantics/platform.git;a=commit;h=bab5c9bd68277c76dc5c20bc7a60a9896cbd1540">gitweb</a>.</p>\r
-</li>\r
-<li>\r
-<p>Ensure that Redmine has a release engineering issue for the branched release, such as <a href="https://www.simantics.org/redmine/issues/7263">Simantics 1.30.0 release engineering</a>. Make a copy of the previous release issue to create the new one. Include link to original issue while copying.</p>\r
-</li>\r
-<li>\r
-<p>Commit the changes made</p>\r
-<pre><code> git commit -a\r
+<h2>Create release branch from selected commit</h2>\r
+<p>When release stabilisation starts, all relevant repositories need to be branched.\r
+When creating major/minor releases <code><commit></code> is usually a commit in the <code>master</code> branch.\r
+With service releases, branch from an existing <code>release/*</code> branch instead.</p>\r
+<p>Instead of doing this clone+branch+push sequence for every SDK repository separately, please use the included <code>release-helper.sh</code> shell script to perform this mechanical work.\r
+The script supports many useful basic git commands which all perform the requested operation on all the release train repositories.\r
+The operations can be seen from the help text printed by the script when given no arguments:</p>\r
+<pre><code>Usage: release-helper.sh <version> <branch-name> <user-name> <command> [<command-arguments>]\r
+\r
+Commands:\r
+ clone The first thing that needs to be done before anything else\r
+ Clones all platform repositories under directory <version>\r
+\r
+Inspection commands:\r
+ diff [args] Run git diff [args] for each platform repository\r
+ log [args] Run git log [args] for each platform repository\r
+ status [args] Run git status [args] for each platform repository\r
+ list-tags Run git tag -l for each repository\r
+\r
+Action:\r
+ add\r
+ branch Run git branch <branch-name> for each platform repository\r
+ checkout Run git checkout <branch-name> for each repository\r
+ commit\r
+ fetch Run git fetch --all for each repository\r
+ pull Run git pull --all for each repository\r
+ push Run git push origin <branch> for each repository\r
+ push-tags Run git push --tags for each repository\r
+ remove-tag Run git tag -d v<branch> for each repository\r
+ reset [args] Run git reset [args] for each repository\r
+ tag Run git checkout <branch> and\r
+ git tag -a v<branch> -m "Simantics <branch> simultaneous release"\r
+ for each repository\r
+\r
+Compound release commands:\r
+ prepare-release-branch <from-branch>\r
+ <from-branch> the name of the branch that the codebase is currently on\r
+\r
+Top-level release commands:\r
+ bump-master-version <from-version> <to-version>\r
+ <from-version> the version string to replace\r
+ <to-version> the replacing new version string\r
+\r
+ branch-release <from-branch>\r
+ <from-branch> the branch to create the service branch from\r
+ e.g. master or release/x.y.z\r
</code></pre>\r
-<p>with the commit message</p>\r
-<pre><code> Configured release/x.y.z[.w] branch for SDK builds.\r
-\r
- refs #xxxx\r
+<p>Begin by cloning all the repositories for working on</p>\r
+<pre><code>user=<your-git-username>\r
+version=x.y.z\r
+branch=release/x.y.z\r
+./release-helper.sh $version $branch $user clone\r
</code></pre>\r
-<p>where <code>#xxxx</code> is the number of the x.y.z[.w] release engineering issue and push them to remote</p>\r
-<pre><code> git push origin release/x.y.z[.w]\r
+<p>This will create a directory called <code>x.y.z</code> under the current working directory and clone all the repositories under it.\r
+The first <code>version</code> argument is only used for the base working directory <code>x.y.z</code>.\r
+The second <code>branch</code> argument tells what branch to specify to some of the available actions, e.g. <code>branch</code>, <code>checkout</code>, etc.</p>\r
+<p>Creating the release branch from master and pushing the new branches to remote happens as follows:</p>\r
+<pre><code># When the commit messages appear, add references to created\r
+# Gitlab release engineering issues by adding this to the commit message:\r
+# \r
+# gitlab #xxxx\r
+#\r
+# where xxxx is the release engineering issue for the respective project\r
+./release-helper.sh $version $branch $user branch-release master\r
+./release-helper.sh $version $branch $user push\r
</code></pre>\r
-</li>\r
-<li>\r
-<p>If you are branching from <code>master</code>, bump the revision of master right now to start the next release cycle in master.\r
-An example of these changes can be seen in <a href="https://www.simantics.org:8088/r/gitweb?p=simantics/platform.git;a=commitdiff;h=ae93c9930c6345c32219e6845b9e72e9d9d2d28c">gitweb</a>.</p>\r
-<p>Commit the changes with the following commit message</p>\r
-<pre><code>Bumped master target and org.simantics.sdk feature versions to x.y.z[.w].\r
-refs #yyyy\r
+<p>If you're creating a service release <code>x.y.w</code> from <code>x.y.z</code> where <code>w > z</code>, do this:</p>\r
+<pre><code>fromBranch=release/x.y.z\r
+branch=release/x.y.w\r
+./release-helper.sh $version $branch $user branch-release $fromBranch\r
+./release-helper.sh $version $branch $user push\r
</code></pre>\r
-<p>where <code>#yyyy</code> is the number of the next release's release engineering issue.</p>\r
-</li>\r
-</ol>\r
-<h3>Initialize release branch distribution web site</h3>\r
+<p>If you branched a new release from <code>master</code>, you should also bump the revision of the master branch right now to start the next release cycle in master.\r
+An example of these changes can be seen in <a href="https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=commit;h=564ac84a2949b19ce5c1c7c838b575527ec42b09">gitweb</a> or in <a href="https://gerrit.simantics.org/r/#/c/1362">review 1362</a>.\r
+The changes include:</p>\r
<ul>\r
-<li>Run <a href="https://www.simantics.org/jenkins/job/SDK/job/Deploy%20External%20Components%20to%20Web/">SDK/Deploy External Components to Web</a> build with parameters:\r
-<ul>\r
-<li><strong>GERRIT_REFNAME:</strong> <code>release/x.y.z[.w]</code></li>\r
-<li><strong>PUBLISH_ARTIFACTS:</strong> <code>true</code></li>\r
+<li>Simantics Desktop splash screen update (version number)</li>\r
+<li>Simantics target platform name to state correct development version</li>\r
+<li>org.simantics.sdk feature version bump</li>\r
+<li>org.simantics.sdk.repository project version bump</li>\r
</ul>\r
-</li>\r
-<li>Run the <a href="https://www.simantics.org/jenkins/job/SDK/job/Simantics%20SDK/">SDK/Simantics SDK</a> build with parameters:\r
+<p>Perform and push the changes <em>in master</em> by running:</p>\r
+<pre><code>branch=master\r
+./release-helper.sh $version $branch $user checkout\r
+./release-helper.sh $version $branch $user bump-master-version x.y.z X.Y.Z\r
+./release-helper.sh $version $branch $user push\r
+</code></pre>\r
+where <code>x.y.z</code> is the old version number of master and <code>X.Y.Z</code> is the new version number.\r
+<h3>Test Release Train build</h3>\r
+<p>Trigger an execution of the <a href="https://www.simantics.org/jenkins/job/simantics-release-train/">simantics-release-train</a> Jenkins job with parameters</p>\r
<ul>\r
-<li><strong>GERRIT_REFNAME:</strong> <code>release/x.y.z[.w]</code></li>\r
-<li><strong>PUBLISH_ARTIFACTS:</strong> <code>true</code></li>\r
+<li>GERRIT_REFNAME: <code>release/x.y.z[.w]</code></li>\r
+<li>PUBLISH_ARTIFACTS: <code>true</code></li>\r
</ul>\r
-</li>\r
-</ul>\r
-<p>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 <code>http://www.simantics.org/download/release/x.y.z[.w]/</code>.</p>\r
-<p>After this, whenever changes are pushed/merged to <code>release/x.y.z[.w]</code> branch in Gerrit, new <strong>SDK/Simantics SDK</strong> builds are triggered automatically and they will publish the results at the same location online.</p>\r
-<p>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 <a href="https://www.simantics.org/jenkins/job/SDK/job/Simantics%20SDK/">SDK/Simantics SDK</a> Jenkins job.</p>\r
+<p>to ensure that all components of the release train build fine and to publish first versions of P2 repositories of everything online.</p>\r
+<p>The release train build is currently never ran automatically.\r
+However, after following all these steps, whenever changes are pushed/merged to <code>release/x.y.z[.w]</code> branch in Gerrit, new Jenkins builds are triggered automatically and they will publish the results (P2 repositories/products) at their designated locations online.</p>\r
+<h4>[Optional reading] Release train build details</h4>\r
+<p>The release train build does two very important steps as the first things,\r
+i.e. build the external dependency P2 repositories for both the\r
+Platform SDK and Simupedia:</p>\r
+<pre><code>stage('External Dependencies') {\r
+ node {\r
+ build job: 'SDK/Deploy External Components to Web', parameters: params1\r
+ build job: 'Member Components/Simupedia/fi.semantum.simupedia.build.p2.site', parameters: params1\r
+ } \r
+}\r
+</code></pre>\r
+<p>After that it builds the Platform SDK and Simupedia before building anything else:</p>\r
+<pre><code>stage('SDK') {\r
+ node {\r
+ build job: 'SDK/Simantics SDK', parameters: params1\r
+ // Note that Simantics SDK builds simupedia-git as well\r
+ }\r
+}\r
+</code></pre>\r
<h2>Review documentation</h2>\r
<p>Documentation to review:</p>\r
<ul>\r
</ul>\r
<h2>Tag release/* branches</h2>\r
<p>When the release branches are ready for the release, tag them with the tag <code>vx.y.z[.w]</code>:</p>\r
-<pre><code>git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
-cd platform \r
-git checkout release/x.y.z[.w]\r
-git tag vx.y.z[.w] -m "Simantics x.y.z[.w] simultaneous release"\r
-git push origin --tags\r
-\r
-git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git\r
-cd third-party\r
-git checkout release/x.y.z[.w]\r
-git tag vx.y.z[.w] -m "Simantics x.y.z[.w] simultaneous release"\r
-git push origin --tags\r
+<pre><code>./release-helper.sh x.y.z release/x.y.z your-git-username checkout\r
+./release-helper.sh x.y.z release/x.y.z your-git-username pull\r
+./release-helper.sh x.y.z release/x.y.z your-git-username tag\r
+./release-helper.sh x.y.z release/x.y.z your-git-username push-tags\r
</code></pre>\r
<blockquote>\r
-<p>Note
The -m argument must be supplied to create an <a href="https://git-scm.com/book/en/v2/Git-Basics-Tagging">annotated tag</a>.
\r+<p>Note
: release-helper.sh will supply the -m argument to git tag to create an <a href="https://git-scm.com/book/en/v2/Git-Basics-Tagging">annotated tag</a>.
\r Only annotated or signed tags can be pushed to Gerrit.</p>\r
</blockquote>\r
<h2>Backup documentation wiki databases</h2>\r
+<p><strong>NOTE: This step is now deprecated since we are in the process of moving all mediawiki-based documentation into the platform git repository.</strong></p>\r
<p>This step is only necessary for major/minor releases, not for service releases.</p>\r
<p>The wiki databases to be backed up are:</p>\r
<ul>\r
</ul>\r
<h2>Disseminate information about the release</h2>\r
<ul>\r
-<li><a href="http://dev.simantics.org">Developer Wiki</a>: Update roadmap at http://dev.simantics.org/index.php/Roadmap</li>\r
-<li><a href="https://www.simantics.org/redmine/">Redmine</a>: Post news on the developer/user-visible changes here.</li>\r
+<li><a href="http://dev.simantics.org">Developer Wiki</a>: Update roadmap at <a href="http://dev.simantics.org/index.php/Roadmap">http://dev.simantics.org/index.php/Roadmap</a></li>\r
+<li><a href="https://www.simantics.org/redmine/">Redmine</a>: Post news on the developer/user-visible changes here</li>\r
<li><a href="https://www.simantics.org">simantics.org</a>: Post news on the release and a link to the redmine post</li>\r
<li><a href="https://www.simantics.org/members/">Members Wiki</a>: Update frame plan to reflect the realized dates and link to Redmine news</li>\r
<li><a href="mailto:simantics-developers@simantics.org">mailto:simantics-developers@simantics.org</a> Send "newsletter" to `simantics-developers@simantics.org:</li>\r
</ul>\r
<p><strong>Newsletter template:</strong></p>\r
<pre><code>Hello everyone,\r
- \r
+\r
Simantics release x.y.z[.w] has been released. Head over to\r
https://www.simantics.org/redmine/news/<news number>\r
for the release news.\r
<hr />\r
<h1>TODO</h1>\r
<ul>\r
-<li>Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release\r
-<ul>\r
-<li>Desktop, Sysdyn, R, Simupedia, FMIL, FMI Studio</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-<ul>\r
-<li>\r
-<p>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</p>\r
-</li>\r
-<li>\r
-<p>Start using https://github.com/mbarbero/fr.obeo.releng.targetplatform to generate <code>.target</code> files. <code>.tpd</code> files allow specifying version ranges instead of specific versions.</p>\r
-</li>\r
+<li>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</li>\r
</ul>\r
\r
</body>\r
Code Review / simantics / platform.git / blobdiff