1 # Definition of Done for Simantics Platform Releases
\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
9 # Simantics Platform Release Process
\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
16 * [https://www.simantics.org/wiki](https://www.simantics.org/wiki) ⇒ [http://www.simantics.org/<version>/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
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
29 In the following sections each task is described step by step.
\r
31 # Simantics Platform Release - Step by Step
\r
33 ## Create release branch from selected commit
\r
35 When release stabilisation starts, branch `simantics/platform` and `simantics/third-party` repositories:
\r
37 git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git
\r
39 git branch release/x.y.z[.w] <commit>
\r
40 git push origin release/x.y.z[.w]
\r
42 git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git
\r
44 git branch release/x.y.z[.w] <commit>
\r
45 git push origin release/x.y.z[.w]
\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
50 ## Prepare release branch for use
\r
52 ### Prepare .target files
\r
54 1. Retrieve release branch of the platform repository
\r
56 git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git
\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
61 2. Edit the beginning of the file `releng/org.simantics.sdk.build.targetdefinition/simantics.target`
\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
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
73 * Change `<repository location=` value to `http://www.simantics.org/download/release/x.y.z[.w]/sdk`
\r
74 * Increment `sequenceNumber` by 1
\r
76 ### Initialize release branch distribution web site
\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
82 ## Review documentation
\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
90 * Read through and get authors to fix found problems, such as TODOs or invalid information.
\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
98 - Build with Buckminster, com.acme.movie.product.site.feature
\r
100 ## Tag release/* branches
\r
102 When the release branches are ready for the release, tag them with the tag `vx.y.z[.w]`:
\r
104 git clone ssh://<user>@www.simantics.org:29418/simantics/platform.git
\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
110 git clone ssh://<user>@www.simantics.org:29418/simantics/third-party.git
\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
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
119 ## Tag documentation wikis
\r
121 Tag documentation wiki using [tag.sh](./tag.sh) script.
\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
128 ## Compile change log entry
\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
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
156 ## Disseminate information about the release
\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
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
172 Simantics Release Engineering Team
\r
175 **News entry template:**
\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
180 Insert some general thoughts on the release...
\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