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 ## Dump documentation wikis\r
 136 \r
 137 Dump documentation wiki using [dump-wikis.sh](./dump-wikis.sh) script.\r
 138 \r
 139 The wiki documentation is mainly in MediaWiki installations. The only\r
 140 sane way to tag the documentation is to back up the mysql database\r
 141 backing the wiki.\r
 142 \r
 143 ## Compile change log entry\r
 144 \r
 145 * 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
 146 * 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
 147 * Open the new link in another browser/tab to start editing the new wiki page\r
 148 * Edit the previous release's page and copy its wiki source contents over to the new release's page.\r
 149 * Fix the content to match the new release:\r
 150   * Remove the issue content of the previous release\r
 151   * Fix release number, release date, release branch link and the link to all issues closed for the release\r
 152     * 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
 153   * Add filter to query: **Release Notes: Any** to only show issues that have some content in their Release Notes field\r
 154   * Export closed issue list as CSV with selected columns only. Open the resulting CSV file in Excel.\r
 155   * Use **Data -> Text to Columns** with tab column separation to columnize the result\r
 156   * Format the list as a table so that there is only one issue / row\r
 157   * Remove all other columns besides: Issue #, Tracker, Release Notes\r
 158   * Format the data into a Textile table:\r
 159     * Copy to table contents as text into [PSPad](http://www.pspad.com/)\r
 160     * Replace (CTRL+H) tabs (`\t`) with `|` with `Regular Expressions` selection checked\r
 161     * Use **Insert Text Into Lines..** (ALT-I) to fix line beginnings and ends:\r
 162       * Text:\r
 163         * At Lines Begin: `|#`\r
 164         * At Lines End: `|`\r
 165   * Copy the resulting textile table over to the change log page\r
 166 * Highlight major issues in the list by changing the text background color of the **Type** column:\r
 167   * `%{background: lightsalmon}Major Bug%`\r
 168   * `%{background: lightgreen}Major Feature%`\r
 169   * `%{background: lightgreen}Major Enhancement%`\r
 170 \r
 171 ## Disseminate information about the release\r
 172 \r
 173 * [Redmine](https://www.simantics.org/redmine/): Post news on the developer/user-visible changes here.\r
 174 * [simantics.org](https://www.simantics.org): Post news on the release and a link to the redmine post\r
 175 * [dev wiki](http://dev.simantics.org): Update roadmap at http://dev.simantics.org/index.php/Roadmap\r
 176 * [simantics-developers@simantics.org](mailto:simantics-developers@simantics.org) Send mail to simantics-developers:\r
 177 \r
 178 **Mail template:**\r
 179 ~~~\r
 180 Hello everyone,\r
 181    \r
 182 Simantics release x.y.z[.w] has been released. Head over to\r
 183 https://www.simantics.org/redmine/news/<news number>\r
 184 for the release news.\r
 185 \r
 186 Best regards,\r
 187 Simantics Release Engineering Team\r
 188 ~~~\r
 189 \r
 190 **News entry template:**\r
 191 ~~~\r
 192 On <date> Simantics x.y.z[.w] was tagged in SVN. Please find change log at:\r
 193 * [[simantics-platform:Simantics_xyzw|Simantics x.y.z.w]]\r
 194 \r
 195 Insert some general thoughts on the release...\r
 196 ~~~\r
 197 \r
 198 ----\r
 199 \r
 200 # TODO\r
 201 \r
 202 * 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
 203 * Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release in one go\r
 204 * 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