From: Tuukka Lehtonen Date: Sun, 18 Dec 2016 17:31:21 +0000 (+0200) Subject: Initial draft of Simantics release engineering instructions X-Git-Tag: v1.25.0~6 X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F04%2F204%2F2;p=simantics%2Fplatform.git Initial draft of Simantics release engineering instructions refs #6621 refs #6848 Change-Id: Id726c100944fd4f1df7c54d9a2eed16a2ca88e6c --- diff --git a/releng/doc/release.html b/releng/doc/release.html new file mode 100644 index 000000000..e92cd1e6e --- /dev/null +++ b/releng/doc/release.html @@ -0,0 +1,518 @@ + + + +MarkdownPad Document + + + + +

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. +
  2. A change log entry 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. +
  3. Roadmap is up-to-date.
    4. +
  4. Tutorials are up-to-date and coherent with the platform.
    5. +
  5. For all new major/minor releases, Wiki documentation is backed up (cloned). This is not necessary for service releases of old release branches.
    6. +
+

Simantics Platform Release Process

+ +

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://<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. +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://<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. +
  2. +

    Edit the beginning of the file releng/org.simantics.sdk.build.targetdefinition/simantics.target

    +
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<?pde version="3.8"?>
+<target name="Simantics 1.25.0" sequenceNumber="10">
+<locations>
+<location includeAllPlatforms="true" includeConfigurePhase="false" includeMode="slicer" includeSource="true" type="InstallableUnit">
+<unit id="org.simantics.sdk.feature.group" version="1.25.0"/>
+<repository location="http://www.simantics.org/download/master/sdk"/>
+</location>
+
    +
      +
    • Change <repository location= value to http://www.simantics.org/download/release/x.y.z[.w]/sdk
      • +
    • Increment sequenceNumber by 1
      • +
    +
    3. +
+

Initialize release branch distribution web site

+ +

Review documentation

+

Documentation to review:

+ +

For each wiki page:

+ +

Review tutorials

+ +

Tag release/* branches

+

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
+
+
+

Note The -m argument must be supplied to create an annotated tag. +Only annotated or signed tags can be pushed to Gerrit.

+
+

Tag documentation wikis

+

Tag documentation wiki using tag.sh script.

+

The wiki documentation is mainly in MediaWiki installations. The only sane way to tag the documentation is to clone it:

+ +

Compile change log entry

+ +

Disseminate information about the release

+ +

Mail 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.
+
+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]]
+
+Insert some general thoughts on the release...
+
+
+

TODO

+ + + + + diff --git a/releng/doc/release.md b/releng/doc/release.md new file mode 100644 index 000000000..a9a681bf2 --- /dev/null +++ b/releng/doc/release.md @@ -0,0 +1,189 @@ +# 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 the beginning of the file `releng/org.simantics.sdk.build.targetdefinition/simantics.target` + ~~~ + + + + + + + + + ~~~ + + * Change `@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. + +## Tag documentation wikis + +Tag documentation wiki using [tag.sh](./tag.sh) script. + +The wiki documentation is mainly in MediaWiki installations. The only sane way to tag the documentation is to clone it: +* Copy the wiki installation from wiki to ${release_version}/wiki +* Copy the trunk wiki MySQL database into a new version +* Reconfigure the tagged wiki (LocalSettings.php) to use the copied database and no longer allow any edits + +## 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. diff --git a/releng/doc/tag-dev-wiki.sh b/releng/doc/tag-dev-wiki.sh new file mode 100644 index 000000000..8a53258b8 --- /dev/null +++ b/releng/doc/tag-dev-wiki.sh @@ -0,0 +1,47 @@ +#!/bin/bash + +major=$1 +minor=$2 +www=/var/www +wikiname=http-dev.simantics.org +wikidb=devwikidb +wikidbuser=devwikiuser + +releasewww=${www}/${major}.${minor} + +srcdb=${wikidb} +tgtdb=${wikidb}_${major}_${minor} + +echo "Release version: $major.$minor" + +function myexecute() { + echo "Sending to mysql using database $1: $2" + echo $2 | mysql -u root -p $1 +} + +# dump wiki db to file +echo "Dumping $srcdb" +mysqldump -p ${srcdb} > ${tgtdb}.dump +# load wiki db from file to name ${wikidb}_x_y, where x_y are major.minor version numbers +# add privileges for ${wikidbuser} to ${wikidb}_x_y +echo "Importing ${tgtdb}" +cat > import_${major}_${minor}.sql < $releasewww/${wikiname}/LocalSettings.php +echo '$wgReadOnly = "Released version, no further changes allowed.";' >> $releasewww/${wikiname}/LocalSettings.php + diff --git a/releng/doc/tag-wiki.sh b/releng/doc/tag-wiki.sh new file mode 100644 index 000000000..14eec0c92 --- /dev/null +++ b/releng/doc/tag-wiki.sh @@ -0,0 +1,49 @@ +#!/bin/bash + +major=$1 +minor=$2 +www=$3 +#www=/var/www/https-www.simantics.org +wikiname=$4 +#wikiname=wiki +wikidb=$5 +wikidbuser=$6 + +releasewww=${www}/${major}.${minor} + +srcdb=${wikidb} +tgtdb=${wikidb}_${major}_${minor} + +echo "Release version: $major.$minor" + +function myexecute() { + echo "Sending to mysql using database $1: $2" + echo $2 | mysql -u root -p $1 +} + +# dump wiki db to file +echo "Dumping $srcdb" +mysqldump -p ${srcdb} > ${tgtdb}.dump +# load wiki db from file to name ${wikidb}_x_y, where x_y are major.minor version numbers +# add privileges for ${wikidbuser} to ${wikidb}_x_y +echo "Importing ${tgtdb}" +cat > import_${major}_${minor}.sql < $releasewww/${wikiname}/LocalSettings.php +echo '$wgReadOnly = "Released version, no further changes allowed.";' >> $releasewww/${wikiname}/LocalSettings.php + diff --git a/releng/doc/tag.sh b/releng/doc/tag.sh new file mode 100644 index 000000000..74297df28 --- /dev/null +++ b/releng/doc/tag.sh @@ -0,0 +1,5 @@ +#!/bin/bash + +./tag-wiki.sh 1 4 /var/www/https-www.simantics.org end_user_wiki enduserwikidb enduserwikiuser +#./tag-dev-wiki.sh 1 4 +