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 the beginning of the file `releng/org.simantics.sdk.build.targetdefinition/simantics.target`\r
  62    ~~~\r
  63    <?xml version="1.0" encoding="UTF-8" standalone="no"?>\r
  64    <?pde version="3.8"?>\r
  65    <target name="Simantics 1.25.0" sequenceNumber="10">\r
  66    <locations>\r
  67    <location includeAllPlatforms="true" includeConfigurePhase="false" includeMode="slicer" includeSource="true" type="InstallableUnit">\r
  68    <unit id="org.simantics.sdk.feature.group" version="1.25.0"/>\r
  69    <repository location="http://www.simantics.org/download/master/sdk"/>\r
  70    </location>\r
  71    ~~~\r
  72 \r
  73    * Change `<repository location=` value to `http://www.simantics.org/download/release/x.y.z[.w]/sdk`\r
  74    * Increment `sequenceNumber` by 1\r
  75 \r
  76 ### Initialize release branch distribution web site\r
  77 \r
  78 * Run the [SDK/Simantics SDK](https://www.simantics.org/jenkins/job/SDK/job/Simantics SDK) build with parameters:\r
  79   * `REFSPEC: refs/heads/release/x.y.z[.w]`\r
  80   * `PUBLISHED_BRANCH_NAME: release/x.y.z[.w]`\r
  81 \r
  82 ## Review documentation\r
  83 \r
  84 Documentation to review:\r
  85 * [Developer wiki](http://dev.simantics.org/)\r
  86 * [End-user wiki](http://www.simantics.org/end_user_wiki)\r
  87 * [Member wiki](http://www.simantics.org/members)\r
  88 \r
  89 For each wiki page:\r
  90 * Read through and get authors to fix found problems, such as TODOs or invalid information.\r
  91 \r
  92 ## Review tutorials\r
  93 \r
  94 * Ensure tutorial wiki documentation at http://dev.simantics.org/index.php/Tutorials is up-to-date with the released platform\r
  95 * Ensure tutorial projects and product build properly\r
  96 \r
  97 * com.acme.movie\r
  98   - Build with Buckminster, com.acme.movie.product.site.feature\r
  99 \r
 100 ## Tag release/* branches\r
 101 \r
 102 When the release branches are ready for the release, tag them with the tag `vx.y.z[.w]`:\r
 103 \r
 104     git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git\r
 105     cd platform    \r
 106     git checkout release/x.y.z[.w]\r
 107     git tag vx.y.z[.w] -m "Simantics x.y.z[.w] release"\r
 108     git push origin --tags\r
 109 \r
 110     git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git\r
 111     cd third-party\r
 112     git checkout release/x.y.z[.w]\r
 113     git tag vx.y.z[.w] -m "Simantics x.y.z[.w] release"\r
 114     git push origin --tags\r
 115 \r
 116 > Note The -m argument must be supplied to create an [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging).\r
 117 > Only annotated or signed tags can be pushed to Gerrit.\r
 118 \r
 119 ## Tag documentation wikis\r
 120 \r
 121 Tag documentation wiki using [tag.sh](./tag.sh) script.\r
 122 \r
 123 The wiki documentation is mainly in MediaWiki installations. The only sane way to tag the documentation is to clone it:\r
 124 * Copy the wiki installation from wiki to ${release_version}/wiki\r
 125 * Copy the trunk wiki MySQL database into a new version\r
 126 * Reconfigure the tagged wiki (LocalSettings.php) to use the copied database and no longer allow any edits\r
 127 \r
 128 ## Compile change log entry\r
 129 \r
 130 * 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
 131 * 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
 132 * Open the new link in another browser/tab to start editing the new wiki page\r
 133 * Edit the previous release's page and copy its wiki source contents over to the new release's page.\r
 134 * Fix the content to match the new release:\r
 135   * Remove the issue content of the previous release\r
 136   * Fix release number, release date, release branch link and the link to all issues closed for the release\r
 137     * 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
 138   * Add filter to query: **Release Notes: Any** to only show issues that have some content in their Release Notes field\r
 139   * Export closed issue list as CSV with selected columns only. Open the resulting CSV file in Excel.\r
 140   * Use **Data -> Text to Columns** with tab column separation to columnize the result\r
 141   * Format the list as a table so that there is only one issue / row\r
 142   * Remove all other columns besides: Issue #, Tracker, Release Notes\r
 143   * Format the data into a Textile table:\r
 144     * Copy to table contents as text into [PSPad](http://www.pspad.com/)\r
 145     * Replace (CTRL+H) tabs (`\t`) with `|` with `Regular Expressions` selection checked\r
 146     * Use **Insert Text Into Lines..** (ALT-I) to fix line beginnings and ends:\r
 147       * Text:\r
 148         * At Lines Begin: `|#`\r
 149         * At Lines End: `|`\r
 150   * Copy the resulting textile table over to the change log page\r
 151 * Highlight major issues in the list by changing the text background color of the **Type** column:\r
 152   * `%{background: lightsalmon}Major Bug%`\r
 153   * `%{background: lightgreen}Major Feature%`\r
 154   * `%{background: lightgreen}Major Enhancement%`\r
 155 \r
 156 ## Disseminate information about the release\r
 157 \r
 158 * [Redmine](https://www.simantics.org/redmine/): Post news on the developer/user-visible changes here.\r
 159 * [simantics.org](https://www.simantics.org): Post news on the release and a link to the redmine post\r
 160 * [dev wiki](http://dev.simantics.org): Update roadmap at http://dev.simantics.org/index.php/Roadmap\r
 161 * [simantics-developers@simantics.org](mailto:simantics-developers@simantics.org) Send mail to simantics-developers:\r
 162 \r
 163 **Mail template:**\r
 164 ~~~\r
 165 Hello everyone,\r
 166    \r
 167 Simantics release x.y.z[.w] has been released. Head over to\r
 168 https://www.simantics.org/redmine/news/<news number>\r
 169 for the release news.\r
 170 \r
 171 Best regards,\r
 172 Simantics Release Engineering Team\r
 173 ~~~\r
 174 \r
 175 **News entry template:**\r
 176 ~~~\r
 177 On <date> Simantics x.y.z[.w] was tagged in SVN. Please find change log at:\r
 178 * [[simantics-platform:Simantics_xyzw|Simantics x.y.z.w]]\r
 179 \r
 180 Insert some general thoughts on the release...\r
 181 ~~~\r
 182 \r
 183 ----\r
 184 \r
 185 # TODO\r
 186 \r
 187 * 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
 188 * Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release in one go\r
 189 * 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