X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=blobdiff_plain;f=releng%2Fdoc%2Frelease.md;h=fc8fcbf81aabf2adb6f8bd0d55ba8d73f87c821d;hp=6d55c144db228408b2b2daf2aa1bf96a6b41ade9;hb=d6223fdc91d3355c12a952e5186dcc4e56407618;hpb=c26409b1caf2f1e560d37c5befd11b442399c3fe diff --git a/releng/doc/release.md b/releng/doc/release.md index 6d55c144d..fc8fcbf81 100644 --- a/releng/doc/release.md +++ b/releng/doc/release.md @@ -1,6 +1,6 @@ # Definition of Done for Simantics Platform Releases -1. The `simantics/platform` and `simantics/third-party` Git repositories have a branch `release/x.y.z[.w]` and tag `x.y.z[.w]`. +1. All Git repositories that are part of the Simantics release train have a branch called `release/x.y.z[.w]` and tag called `x.y.z[.w]`. 2. [A change log entry](https://www.simantics.org/redmine/projects/simantics-platform/wiki/ChangeLog) 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. 3. [Roadmap](http://dev.simantics.org/index.php/Roadmap) is up-to-date. 4. [Tutorials](http://dev.simantics.org/index.php/Tutorials) are up-to-date and coherent with the platform. @@ -22,23 +22,35 @@ ---- -# Released Plug-in Components and Products +# Released Plug-in Components and Products -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. +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. -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. +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. -Products that are part of the release train: -* Simantics Desktop -* Simantics System Dynamics Tool - [simantics/sysdyn.git](https://www.simantics.org:8088/r/gitweb?p=simantics/sysdyn.git;a=summary) +Core components of the release train: +* External third party library dependencies required by the platform - [simantics/third-party.git](https://gerrit.simantics.org/r/gitweb?p=simantics/third-party.git;a=summary) +* The Simantics Platform - [simantics/platform.git](https://gerrit.simantics.org/r/gitweb?p=simantics/platform.git;a=summary) Plug-in components that are part of the release train: -* Simantics R - [simantics/r.git](https://www.simantics.org:8088/r/gitweb?p=simantics/r.git;a=summary) -* FMIL - [simantics/fmil.git](https://www.simantics.org:8088/r/gitweb?p=simantics/fmil.git;a=summary) -* FMI Studio - [members/fmi.git](https://www.simantics.org:8088/r/gitweb?p=members/fmi.git;a=summary) -* Simupedia - [Members SVN](https://www.simantics.org/svn/members/simupedia) +* Simupedia - [members/simupedia.git](https://gerrit.simantics.org/r/gitweb?p=members/simupedia.git;a=summary) +* FMIL - [simantics/fmil.git](https://gerrit.simantics.org/r/gitweb?p=simantics/fmil.git;a=summary) +* FMI Studio - [members/fmi.git](https://gerrit.simantics.org/r/gitweb?p=members/fmi.git;a=summary) +* Interoperability components - [simantics/interop.git](https://gerrit.simantics.org/r/gitweb?p=simantics/interop.git;a=summary) +* Simantics R binding - [simantics/r.git](https://gerrit.simantics.org/r/gitweb?p=simantics/r.git;a=summary) +* Matlab SCL binding - [simantics/matlab.git](https://gerrit.simantics.org/r/gitweb?p=simantics/matlab.git;a=summary) +* Python SCL binding - [simantics/python.git](https://gerrit.simantics.org/r/gitweb?p=simantics/python.git;a=summary) +* Simantics System Dynamics - [simantics/sysdyn.git](https://gerrit.simantics.org/r/gitweb?p=simantics/sysdyn.git;a=summary) +* Simantics District modelling components - [simantics/district.git](https://gerrit.simantics.org/r/gitweb?p=simantics/district.git;a=summary) +* Simantics 3D modelling components - [simantics/3d.git](https://gerrit.simantics.org/r/gitweb?p=simantics/3d.git;a=summary) +* Simantics Proteus toolset - [gold-members/proteus.git](https://gerrit.simantics.org/r/gitweb?p=gold-members/proteus.git;a=summary) + +Products that are part of the release train: +* Simantics Desktop +* Simantics System Dynamics Tool + * This is Simantics Desktop with Simantics System Dynamics Tool features installed -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. +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. ---- @@ -52,88 +64,145 @@ For simplicity, each of these components are versioned accoring to platform vers # Simantics Platform Release - Step by Step -## Create release branch from selected commit - -When release stabilisation starts, branch `simantics/platform` and `simantics/third-party` repositories: +## Create release engineering issue(s) in Gitlab - git clone ssh://@www.simantics.org:29418/simantics/platform.git - cd platform - git branch release/x.y.z[.w] - git push origin release/x.y.z[.w] +Ensure that Gitlab has a release engineering issue for the branched release, +such as [Simantics 1.34.0 release engineering](https://gitlab.simantics.org/simantics/platform/issues/16) +* Make a new release issue with title `$version release engineering`. +* Add a link to the previous previous release's issue in the new issue description, e.g. `simantics/platform#16`. +* Add labels `releng` and `$version` to the new issue - git clone ssh://@www.simantics.org:29418/simantics/third-party.git - cd third-party - git branch release/x.y.z[.w] - git push origin release/x.y.z[.w] +## Create release branch from selected commit +When release stabilisation starts, all relevant repositories need to be branched. When creating major/minor releases `` is usually a commit in the `master` branch. With service releases, branch from an existing `release/*` branch instead. -## Prepare release branch for use - -### Prepare .target files - -1. Retrieve release branch of the platform repository - - git clone ssh://@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 and replace - the version numbers in target name and `org.simantics.sdk.feature.group` and - `org.simantics.sdk.source.feature.group` with `x.y.z[.w]`: - ~~~ - - - - - - ~~~ - - Next, replace the following rows in both mentioned files: - - ~~~ - - - - ~~~ - - with - - ~~~ - - - - ~~~ - -3. Edit version number of `org.simantics.sdk` feature in `features/org.simantics.sdk.feature/feature.xml` to `x.y.z[.w]`. - ~~~ - - ~~~ - -### 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 [] + +Commands: + clone The first thing that needs to be done before anything else + Clones all platform repositories under directory + +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 for each platform repository + checkout Run git checkout 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 for each repository + push-tags Run git push --tags for each repository + remove-tag Run git tag -d v for each repository + reset [args] Run git reset [args] for each repository + tag Run git checkout and + git tag -a v -m "Simantics simultaneous release" + for each repository + +Compound release commands: + prepare-release-branch + the name of the branch that the codebase is currently on + +Top-level release commands: + bump-master-version + the version string to replace + the replacing new version string + + branch-release + 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= + 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 *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 + +where `x.y.z` is the old version number of master and `X.Y.Z` is the new version number. + +### 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 + } +} +~~~ ## Review documentation @@ -157,22 +226,17 @@ 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://@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://@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](https://git-scm.com/book/en/v2/Git-Basics-Tagging). +> Note: release-helper.sh will supply the -m argument to git tag to create an [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). > Only annotated or signed tags can be pushed to Gerrit. -## Backup documentation wiki databases +## 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. @@ -183,7 +247,7 @@ 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. +separate Mediawiki installation. 1. Dump documentation wiki databases using [dump-wikis.sh](./dump-wikis.sh) script. 2. Put the generated backup x.y.z.tar.gz at /var/backup/simantics-releases/x.y.z/wiki/ @@ -218,8 +282,8 @@ separate Mediawiki installation. ## Disseminate information about the release -* [Developer Wiki](http://dev.simantics.org): Update roadmap at http://dev.simantics.org/index.php/Roadmap -* [Redmine](https://www.simantics.org/redmine/): Post news on the developer/user-visible changes here. +* [Developer Wiki](http://dev.simantics.org): Update roadmap at [http://dev.simantics.org/index.php/Roadmap](http://dev.simantics.org/index.php/Roadmap) +* [Redmine](https://www.simantics.org/redmine/): Post news on the developer/user-visible changes here * [simantics.org](https://www.simantics.org): Post news on the release and a link to the redmine post * [Members Wiki](https://www.simantics.org/members/): Update frame plan to reflect the realized dates and link to Redmine news * [mailto:simantics-developers@simantics.org](mailto:simantics-developers@simantics.org) Send "newsletter" to `simantics-developers@simantics.org: @@ -227,7 +291,7 @@ separate Mediawiki installation. **Newsletter template:** ~~~ Hello everyone, - + Simantics release x.y.z[.w] has been released. Head over to https://www.simantics.org/redmine/news/ for the release news. @@ -250,11 +314,4 @@ Insert some general thoughts on the release... # TODO -* Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release - * Desktop, Sysdyn, R, Simupedia, FMIL, FMI Studio - - * 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 - -* Start using https://github.com/mbarbero/fr.obeo.releng.targetplatform to generate `.target` files. `.tpd` files allow specifying version ranges instead of specific versions. -