# 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]`. 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. 5. For all new major/minor releases, Wiki documentation is backed up (cloned). This is not necessary for service releases of old release branches. # Simantics Platform Release Process * Create `release/x.y.z[.w]` release stabilisation branch * Repeat until stable: * Develop, test and document components and test products * Tag the release in repository * Tag documentation * [https://www.simantics.org/wiki](https://www.simantics.org/wiki) ⇒ [http://www.simantics.org/<version>/wiki](http://www.simantics.org//wiki) * Build and publish SDK package with and without sources * Build Simantics open source products and plug-in components which are a part of the release train * Simantics Sysdyn * Simantics R * Simupedia * FMI Studio * Update websites to reflect the new release * [dev.simantics.org](http://dev.simantics.org) * [www.simantics.org/end_user_wiki/](https://www.simantics.org/end_user_wiki/) * [www.simantics.org/members/](https://www.simantics.org/members/) * [www.simantics.org](https://www.simantics.org) In the following sections each task is described step by step. # Simantics Platform Release - Step by Step ## Create release branch from selected commit When release stabilisation starts, branch `simantics/platform` and `simantics/third-party` repositories: 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] 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] 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` * `org.simantics.sdk.build.targetdefinition-semantum.target` At the beginning of each .target file, increment `sequenceNumber` by 1 ~~~ ~~~ Next, replace the following rows in those files: ~~~ ~~~ with ~~~ ~~~ ### 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` ## Review documentation Documentation to review: * [Developer wiki](http://dev.simantics.org/) * [End-user wiki](http://www.simantics.org/end_user_wiki) * [Member wiki](http://www.simantics.org/members) For each wiki page: * Read through and get authors to fix found problems, such as TODOs or invalid information. ## Review tutorials * Ensure tutorial wiki documentation at http://dev.simantics.org/index.php/Tutorials is up-to-date with the released platform * Ensure tutorial projects and product build properly * com.acme.movie - Build with Buckminster, com.acme.movie.product.site.feature ## Tag release/* branches 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 > Note The -m argument must be supplied 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. ## Dump documentation wikis Dump documentation wiki using [dump-wikis.sh](./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. ## Compile change log entry * Edit the [main page](https://www.simantics.org/redmine/projects/simantics-platform/wiki/ChangeLog) and add a a link for release x.y.z[.w]. * Open the change log page of the previous release, e.g. [1.25.0](https://www.simantics.org/redmine/projects/simantics-platform/wiki/Simantics_1250) * Open the new link in another browser/tab to start editing the new wiki page * Edit the previous release's page and copy its wiki source contents over to the new release's page. * Fix the content to match the new release: * Remove the issue content of the previous release * Fix release number, release date, release branch link and the link to all issues closed for the release * Save new public issue query that lists all issues closed for the release by [starting from the previous release's query](https://www.simantics.org/redmine/projects/simantics-platform/issues?query_id=122) * Add filter to query: **Release Notes: Any** to only show issues that have some content in their Release Notes field * Export closed issue list as CSV with selected columns only. Open the resulting CSV file in Excel. * Use **Data -> Text to Columns** with tab column separation to columnize the result * Format the list as a table so that there is only one issue / row * Remove all other columns besides: Issue #, Tracker, Release Notes * Format the data into a Textile table: * Copy to table contents as text into [PSPad](http://www.pspad.com/) * Replace (CTRL+H) tabs (`\t`) with `|` with `Regular Expressions` selection checked * Use **Insert Text Into Lines..** (ALT-I) to fix line beginnings and ends: * Text: * At Lines Begin: `|#` * At Lines End: `|` * Copy the resulting textile table over to the change log page * Highlight major issues in the list by changing the text background color of the **Type** column: * `%{background: lightsalmon}Major Bug%` * `%{background: lightgreen}Major Feature%` * `%{background: lightgreen}Major Enhancement%` ## Disseminate information about the release * [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 * [dev wiki](http://dev.simantics.org): Update roadmap at http://dev.simantics.org/index.php/Roadmap * [simantics-developers@simantics.org](mailto:simantics-developers@simantics.org) Send mail to simantics-developers: **Mail 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. Best regards, Simantics Release Engineering Team ~~~ **News entry template:** ~~~ On Simantics x.y.z[.w] was tagged in SVN. Please find change log at: * [[simantics-platform:Simantics_xyzw|Simantics x.y.z.w]] 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.