releng/doc/release.md

   1 # Definition of Done for Simantics Platform Releases\r
   2 \r
   3 1. The `simantics/platform` and `simantics/third-party` Git repositories have a branch `release/x.y.z[.w]` and tag `x.y.z[.w]`.\r
   4 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.\r
   5 3. [Roadmap](http://dev.simantics.org/index.php/Roadmap) is up-to-date.\r
   6 4. [Tutorials](http://dev.simantics.org/index.php/Tutorials) are up-to-date and coherent with the platform.\r
   7 5. For all new major/minor releases, Wiki documentation is backed up (cloned). This is not necessary for service releases of old release branches.\r
   8 \r
   9 # Simantics Platform Release Process\r
  10 \r
  11 * Create `release/x.y.z[.w]` release stabilisation branch\r
  12 * Repeat until stable:\r
  13   * Develop, test and document components and test products\r
  14 * Tag the release in repository\r
  15 * Tag documentation\r
  16   * [https://www.simantics.org/wiki](https://www.simantics.org/wiki) &rArr; [http://www.simantics.org/&lt;version&gt;/wiki](http://www.simantics.org/<version>/wiki)\r
  17 * Build and publish SDK package with and without sources\r
  18 * Build Simantics open source products and plug-in components which are a part of the release train\r
  19   * Simantics Sysdyn\r
  20   * Simantics R\r
  21   * Simupedia\r
  22   * FMI Studio\r
  23 * Update websites to reflect the new release\r
  24   * [dev.simantics.org](http://dev.simantics.org)\r
  25   * [www.simantics.org/end_user_wiki/](https://www.simantics.org/end_user_wiki/)\r
  26   * [www.simantics.org/members/](https://www.simantics.org/members/)\r
  27   * [www.simantics.org](https://www.simantics.org)\r
  28 \r
  29 In the following sections each task is described step by step.\r
  30 \r
  31 # Simantics Platform Release - Step by Step\r
  32 \r
  33 ## Create release branch from selected commit\r
  34 \r
  35 When release stabilisation starts, branch `simantics/platform` and `simantics/third-party` repositories:\r
  36 \r
  37     git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
  38     cd platform\r
  39     git branch release/x.y.z[.w] <commit>\r
  40     git push origin release/x.y.z[.w]\r
  41 \r
  42     git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git\r
  43     cd third-party\r
  44     git branch release/x.y.z[.w] <commit>\r
  45     git push origin release/x.y.z[.w]\r
  46 \r
  47 When creating major/minor releases `<commit>` is usually a commit in the `master` branch.\r
  48 With service releases, branch from an existing `release/*` branch instead.\r
  49 \r
  50 ## Prepare release branch for use\r
  51 \r
  52 ### Prepare .target files\r
  53 \r
  54 1. Retrieve release branch of the platform repository\r
  55 \r
  56        git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
  57        cd platform\r
  58        git branch release/x.y.z[.w] remotes/origin/release/x.y.z[.w]\r
  59        git checkout release/x.y.z[.w]\r
  60 \r
  61 2. Edit all target platform files in  `releng/org.simantics.sdk.build.targetdefinition/`, i.e.\r
  62    * `simantics.target`\r
  63    * `org.simantics.sdk.build.targetdefinition.target`\r
  64    * `org.simantics.sdk.build.targetdefinition-semantum.target`\r
  65 \r
  66    At the beginning of each .target file, increment `sequenceNumber` by 1\r
  67    ~~~\r
  68    <?xml version="1.0" encoding="UTF-8" standalone="no"?>\r
  69    <?pde version="3.8"?>\r
  70    <target name="Simantics x.y.z[.w]" sequenceNumber="11">\r
  71    ~~~\r
  72 \r
  73    Next, replace the following rows in those files:   \r
  74 \r
  75    ~~~\r
  76    <repository location="http://www.simantics.org/download/master/sdk"/>\r
  77    <repository location="http://www.simantics.org/download/master/external-components/maven"/>\r
  78    <repository location="http://www.simantics.org/download/master/external-components/manual"/>\r
  79    ~~~\r
  80 \r
  81    with\r
  82 \r
  83    ~~~\r
  84    <repository location="http://www.simantics.org/download/release/x.y.z[.w]/sdk"/>\r
  85    <repository location="http://www.simantics.org/download/release/x.y.z[.w]/external-components/maven"/>\r
  86    <repository location="http://www.simantics.org/download/release/x.y.z[.w]/external-components/manual"/>\r
  87    ~~~\r
  88 \r
  89 ### Initialize release branch distribution web site\r
  90 \r
  91 * Run [SDK/Deploy External Components to Web](https://www.simantics.org/jenkins/job/SDK/job/Deploy%20External%20Components%20to%20Web/) build with parameters:\r
  92   * **GERRIT_REFNAME:** `release/x.y.z[.w]`\r
  93   * **PUBLISH_ARTIFACTS:** `true`\r
  94 * Run the [SDK/Simantics SDK](https://www.simantics.org/jenkins/job/SDK/job/Simantics%20SDK/) build with parameters:\r
  95   * **GERRIT_REFNAME:** `release/x.y.z[.w]`\r
  96   * **PUBLISH_ARTIFACTS:** `true`\r
  97 \r
  98 ## Review documentation\r
  99 \r
 100 Documentation to review:\r
 101 * [Developer wiki](http://dev.simantics.org/)\r
 102 * [End-user wiki](http://www.simantics.org/end_user_wiki)\r
 103 * [Member wiki](http://www.simantics.org/members)\r
 104 \r
 105 For each wiki page:\r
 106 * Read through and get authors to fix found problems, such as TODOs or invalid information.\r
 107 \r
 108 ## Review tutorials\r
 109 \r
 110 * Ensure tutorial wiki documentation at http://dev.simantics.org/index.php/Tutorials is up-to-date with the released platform\r
 111 * Ensure tutorial projects and product build properly\r
 112 \r
 113 * com.acme.movie\r
 114   - Build with Buckminster, com.acme.movie.product.site.feature\r
 115 \r
 116 ## Tag release/* branches\r
 117 \r
 118 When the release branches are ready for the release, tag them with the tag `vx.y.z[.w]`:\r
 119 \r
 120     git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
 121     cd platform    \r
 122     git checkout release/x.y.z[.w]\r
 123     git tag vx.y.z[.w] -m "Simantics x.y.z[.w] release"\r
 124     git push origin --tags\r
 125 \r
 126     git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git\r
 127     cd third-party\r
 128     git checkout release/x.y.z[.w]\r
 129     git tag vx.y.z[.w] -m "Simantics x.y.z[.w] release"\r
 130     git push origin --tags\r
 131 \r
 132 > Note The -m argument must be supplied to create an [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging).\r
 133 > Only annotated or signed tags can be pushed to Gerrit.\r
 134 \r
 135 ## Tag documentation wikis\r
 136 \r
 137 Tag documentation wiki using [tag.sh](./tag.sh) script.\r
 138 \r
 139 The wiki documentation is mainly in MediaWiki installations. The only sane way to tag the documentation is to clone it:\r
 140 * Copy the wiki installation from wiki to ${release_version}/wiki\r
 141 * Copy the trunk wiki MySQL database into a new version\r
 142 * Reconfigure the tagged wiki (LocalSettings.php) to use the copied database and no longer allow any edits\r
 143 \r
 144 ## Compile change log entry\r
 145 \r
 146 * 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].\r
 147 * 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)\r
 148 * Open the new link in another browser/tab to start editing the new wiki page\r
 149 * Edit the previous release's page and copy its wiki source contents over to the new release's page.\r
 150 * Fix the content to match the new release:\r
 151   * Remove the issue content of the previous release\r
 152   * Fix release number, release date, release branch link and the link to all issues closed for the release\r
 153     * 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)\r
 154   * Add filter to query: **Release Notes: Any** to only show issues that have some content in their Release Notes field\r
 155   * Export closed issue list as CSV with selected columns only. Open the resulting CSV file in Excel.\r
 156   * Use **Data -> Text to Columns** with tab column separation to columnize the result\r
 157   * Format the list as a table so that there is only one issue / row\r
 158   * Remove all other columns besides: Issue #, Tracker, Release Notes\r
 159   * Format the data into a Textile table:\r
 160     * Copy to table contents as text into [PSPad](http://www.pspad.com/)\r
 161     * Replace (CTRL+H) tabs (`\t`) with `|` with `Regular Expressions` selection checked\r
 162     * Use **Insert Text Into Lines..** (ALT-I) to fix line beginnings and ends:\r
 163       * Text:\r
 164         * At Lines Begin: `|#`\r
 165         * At Lines End: `|`\r
 166   * Copy the resulting textile table over to the change log page\r
 167 * Highlight major issues in the list by changing the text background color of the **Type** column:\r
 168   * `%{background: lightsalmon}Major Bug%`\r
 169   * `%{background: lightgreen}Major Feature%`\r
 170   * `%{background: lightgreen}Major Enhancement%`\r
 171 \r
 172 ## Disseminate information about the release\r
 173 \r
 174 * [Redmine](https://www.simantics.org/redmine/): Post news on the developer/user-visible changes here.\r
 175 * [simantics.org](https://www.simantics.org): Post news on the release and a link to the redmine post\r
 176 * [dev wiki](http://dev.simantics.org): Update roadmap at http://dev.simantics.org/index.php/Roadmap\r
 177 * [simantics-developers@simantics.org](mailto:simantics-developers@simantics.org) Send mail to simantics-developers:\r
 178 \r
 179 **Mail template:**\r
 180 ~~~\r
 181 Hello everyone,\r
 182    \r
 183 Simantics release x.y.z[.w] has been released. Head over to\r
 184 https://www.simantics.org/redmine/news/<news number>\r
 185 for the release news.\r
 186 \r
 187 Best regards,\r
 188 Simantics Release Engineering Team\r
 189 ~~~\r
 190 \r
 191 **News entry template:**\r
 192 ~~~\r
 193 On <date> Simantics x.y.z[.w] was tagged in SVN. Please find change log at:\r
 194 * [[simantics-platform:Simantics_xyzw|Simantics x.y.z.w]]\r
 195 \r
 196 Insert some general thoughts on the release...\r
 197 ~~~\r
 198 \r
 199 ----\r
 200 \r
 201 # TODO\r
 202 \r
 203 * 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\r
 204 * Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release in one go\r
 205 * Start using https://github.com/mbarbero/fr.obeo.releng.targetplatform to generate `.target` files. `.tpd` files allow specifying version ranges instead of specific versions.\r