]> gerrit.simantics Code Review - simantics/platform.git/blob - releng/doc/release.html
0708ef4c326f5c9a5d057d84ee4dc14591f52ea3
[simantics/platform.git] / releng / doc / release.html
1 <!DOCTYPE html>\r
2 <html>\r
3 <head>\r
4 <title>MarkdownPad Document</title>\r
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />\r
6 <style type="text/css">\r
7 /* GitHub stylesheet for MarkdownPad (http://markdownpad.com) */\r
8 /* Author: Nicolas Hery - http://nicolashery.com */\r
9 /* Version: b13fe65ca28d2e568c6ed5d7f06581183df8f2ff */\r
10 /* Source: https://github.com/nicolahery/markdownpad-github */\r
11 \r
12 /* RESET\r
13 =============================================================================*/\r
14 \r
15 html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video {\r
16   margin: 0;\r
17   padding: 0;\r
18   border: 0;\r
19 }\r
20 \r
21 /* BODY\r
22 =============================================================================*/\r
23 \r
24 body {\r
25   font-family: Helvetica, arial, freesans, clean, sans-serif;\r
26   font-size: 14px;\r
27   line-height: 1.6;\r
28   color: #333;\r
29   background-color: #fff;\r
30   padding: 20px;\r
31   max-width: 960px;\r
32   margin: 0 auto;\r
33 }\r
34 \r
35 body>*:first-child {\r
36   margin-top: 0 !important;\r
37 }\r
38 \r
39 body>*:last-child {\r
40   margin-bottom: 0 !important;\r
41 }\r
42 \r
43 /* BLOCKS\r
44 =============================================================================*/\r
45 \r
46 p, blockquote, ul, ol, dl, table, pre {\r
47   margin: 15px 0;\r
48 }\r
49 \r
50 /* HEADERS\r
51 =============================================================================*/\r
52 \r
53 h1, h2, h3, h4, h5, h6 {\r
54   margin: 20px 0 10px;\r
55   padding: 0;\r
56   font-weight: bold;\r
57   -webkit-font-smoothing: antialiased;\r
58 }\r
59 \r
60 h1 tt, h1 code, h2 tt, h2 code, h3 tt, h3 code, h4 tt, h4 code, h5 tt, h5 code, h6 tt, h6 code {\r
61   font-size: inherit;\r
62 }\r
63 \r
64 h1 {\r
65   font-size: 28px;\r
66   color: #000;\r
67 }\r
68 \r
69 h2 {\r
70   font-size: 24px;\r
71   border-bottom: 1px solid #ccc;\r
72   color: #000;\r
73 }\r
74 \r
75 h3 {\r
76   font-size: 18px;\r
77 }\r
78 \r
79 h4 {\r
80   font-size: 16px;\r
81 }\r
82 \r
83 h5 {\r
84   font-size: 14px;\r
85 }\r
86 \r
87 h6 {\r
88   color: #777;\r
89   font-size: 14px;\r
90 }\r
91 \r
92 body>h2:first-child, body>h1:first-child, body>h1:first-child+h2, body>h3:first-child, body>h4:first-child, body>h5:first-child, body>h6:first-child {\r
93   margin-top: 0;\r
94   padding-top: 0;\r
95 }\r
96 \r
97 a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {\r
98   margin-top: 0;\r
99   padding-top: 0;\r
100 }\r
101 \r
102 h1+p, h2+p, h3+p, h4+p, h5+p, h6+p {\r
103   margin-top: 10px;\r
104 }\r
105 \r
106 /* LINKS\r
107 =============================================================================*/\r
108 \r
109 a {\r
110   color: #4183C4;\r
111   text-decoration: none;\r
112 }\r
113 \r
114 a:hover {\r
115   text-decoration: underline;\r
116 }\r
117 \r
118 /* LISTS\r
119 =============================================================================*/\r
120 \r
121 ul, ol {\r
122   padding-left: 30px;\r
123 }\r
124 \r
125 ul li > :first-child, \r
126 ol li > :first-child, \r
127 ul li ul:first-of-type, \r
128 ol li ol:first-of-type, \r
129 ul li ol:first-of-type, \r
130 ol li ul:first-of-type {\r
131   margin-top: 0px;\r
132 }\r
133 \r
134 ul ul, ul ol, ol ol, ol ul {\r
135   margin-bottom: 0;\r
136 }\r
137 \r
138 dl {\r
139   padding: 0;\r
140 }\r
141 \r
142 dl dt {\r
143   font-size: 14px;\r
144   font-weight: bold;\r
145   font-style: italic;\r
146   padding: 0;\r
147   margin: 15px 0 5px;\r
148 }\r
149 \r
150 dl dt:first-child {\r
151   padding: 0;\r
152 }\r
153 \r
154 dl dt>:first-child {\r
155   margin-top: 0px;\r
156 }\r
157 \r
158 dl dt>:last-child {\r
159   margin-bottom: 0px;\r
160 }\r
161 \r
162 dl dd {\r
163   margin: 0 0 15px;\r
164   padding: 0 15px;\r
165 }\r
166 \r
167 dl dd>:first-child {\r
168   margin-top: 0px;\r
169 }\r
170 \r
171 dl dd>:last-child {\r
172   margin-bottom: 0px;\r
173 }\r
174 \r
175 /* CODE\r
176 =============================================================================*/\r
177 \r
178 pre, code, tt {\r
179   font-size: 12px;\r
180   font-family: Consolas, "Liberation Mono", Courier, monospace;\r
181 }\r
182 \r
183 code, tt {\r
184   margin: 0 0px;\r
185   padding: 0px 0px;\r
186   white-space: nowrap;\r
187   border: 1px solid #eaeaea;\r
188   background-color: #f8f8f8;\r
189   border-radius: 3px;\r
190 }\r
191 \r
192 pre>code {\r
193   margin: 0;\r
194   padding: 0;\r
195   white-space: pre;\r
196   border: none;\r
197   background: transparent;\r
198 }\r
199 \r
200 pre {\r
201   background-color: #f8f8f8;\r
202   border: 1px solid #ccc;\r
203   font-size: 13px;\r
204   line-height: 19px;\r
205   overflow: auto;\r
206   padding: 6px 10px;\r
207   border-radius: 3px;\r
208 }\r
209 \r
210 pre code, pre tt {\r
211   background-color: transparent;\r
212   border: none;\r
213 }\r
214 \r
215 kbd {\r
216     -moz-border-bottom-colors: none;\r
217     -moz-border-left-colors: none;\r
218     -moz-border-right-colors: none;\r
219     -moz-border-top-colors: none;\r
220     background-color: #DDDDDD;\r
221     background-image: linear-gradient(#F1F1F1, #DDDDDD);\r
222     background-repeat: repeat-x;\r
223     border-color: #DDDDDD #CCCCCC #CCCCCC #DDDDDD;\r
224     border-image: none;\r
225     border-radius: 2px 2px 2px 2px;\r
226     border-style: solid;\r
227     border-width: 1px;\r
228     font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;\r
229     line-height: 10px;\r
230     padding: 1px 4px;\r
231 }\r
232 \r
233 /* QUOTES\r
234 =============================================================================*/\r
235 \r
236 blockquote {\r
237   border-left: 4px solid #DDD;\r
238   padding: 0 15px;\r
239   color: #777;\r
240 }\r
241 \r
242 blockquote>:first-child {\r
243   margin-top: 0px;\r
244 }\r
245 \r
246 blockquote>:last-child {\r
247   margin-bottom: 0px;\r
248 }\r
249 \r
250 /* HORIZONTAL RULES\r
251 =============================================================================*/\r
252 \r
253 hr {\r
254   clear: both;\r
255   margin: 15px 0;\r
256   height: 0px;\r
257   overflow: hidden;\r
258   border: none;\r
259   background: transparent;\r
260   border-bottom: 4px solid #ddd;\r
261   padding: 0;\r
262 }\r
263 \r
264 /* TABLES\r
265 =============================================================================*/\r
266 \r
267 table th {\r
268   font-weight: bold;\r
269 }\r
270 \r
271 table th, table td {\r
272   border: 1px solid #ccc;\r
273   padding: 6px 13px;\r
274 }\r
275 \r
276 table tr {\r
277   border-top: 1px solid #ccc;\r
278   background-color: #fff;\r
279 }\r
280 \r
281 table tr:nth-child(2n) {\r
282   background-color: #f8f8f8;\r
283 }\r
284 \r
285 /* IMAGES\r
286 =============================================================================*/\r
287 \r
288 img {\r
289   max-width: 100%\r
290 }\r
291 </style>\r
292 </head>\r
293 <body>\r
294 <h1>Definition of Done for Simantics Platform Releases</h1>\r
295 <ol>\r
296 <li>The <code>simantics/platform</code> and <code>simantics/third-party</code> Git repositories have a branch <code>release/x.y.z[.w]</code> and tag <code>x.y.z[.w]</code>.</li>\r
297 <li><a href="https://www.simantics.org/redmine/projects/simantics-platform/wiki/ChangeLog">A change log entry</a> 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.</li>\r
298 <li><a href="http://dev.simantics.org/index.php/Roadmap">Roadmap</a> is up-to-date.</li>\r
299 <li><a href="http://dev.simantics.org/index.php/Tutorials">Tutorials</a> are up-to-date and coherent with the platform.</li>\r
300 <li>For all new major/minor releases, Wiki documentation is backed up (cloned). This is not necessary for service releases of old release branches.</li>\r
301 </ol>\r
302 <h1>Simantics Platform Release Process</h1>\r
303 <ul>\r
304 <li>Create <code>release/x.y.z[.w]</code> release stabilisation branch</li>\r
305 <li>Repeat until stable:\r
306 <ul>\r
307 <li>Develop, test and document components and test products</li>\r
308 </ul>\r
309 </li>\r
310 <li>Tag the release in repository</li>\r
311 <li>Tag documentation\r
312 <ul>\r
313 <li><a href="https://www.simantics.org/wiki">https://www.simantics.org/wiki</a> â‡’ <a href="http://www.simantics.org/%3Cversion%3E/wiki">http://www.simantics.org/&lt;version&gt;/wiki</a></li>\r
314 </ul>\r
315 </li>\r
316 <li>Build and publish SDK package with and without sources</li>\r
317 <li>Build Simantics open source products and plug-in components which are a part of the release train\r
318 <ul>\r
319 <li>Simantics Sysdyn</li>\r
320 <li>Simantics R</li>\r
321 <li>Simupedia</li>\r
322 <li>FMI Studio</li>\r
323 </ul>\r
324 </li>\r
325 <li>Update websites to reflect the new release\r
326 <ul>\r
327 <li><a href="http://dev.simantics.org">dev.simantics.org</a></li>\r
328 <li><a href="https://www.simantics.org/end_user_wiki/">www.simantics.org/end_user_wiki/</a></li>\r
329 <li><a href="https://www.simantics.org/members/">www.simantics.org/members/</a></li>\r
330 <li><a href="https://www.simantics.org">www.simantics.org</a></li>\r
331 </ul>\r
332 </li>\r
333 </ul>\r
334 <p>In the following sections each task is described step by step.</p>\r
335 <h1>Simantics Platform Release - Step by Step</h1>\r
336 <h2>Create release branch from selected commit</h2>\r
337 <p>When release stabilisation starts, branch <code>simantics/platform</code> and <code>simantics/third-party</code> repositories:</p>\r
338 <pre><code>git clone ssh://&lt;user&gt;@www.simantics.org:29418/simantics/platform.git\r
339 cd platform\r
340 git branch release/x.y.z[.w] &lt;commit&gt;\r
341 git push origin release/x.y.z[.w]\r
342 \r
343 git clone ssh://&lt;user&gt;@www.simantics.org:29418/simantics/third-party.git\r
344 cd third-party\r
345 git branch release/x.y.z[.w] &lt;commit&gt;\r
346 git push origin release/x.y.z[.w]\r
347 </code></pre>\r
348 <p>When creating major/minor releases <code>&lt;commit&gt;</code> is usually a commit in the <code>master</code> branch.\r
349 With service releases, branch from an existing <code>release/*</code> branch instead.</p>\r
350 <h2>Prepare release branch for use</h2>\r
351 <h3>Prepare .target files</h3>\r
352 <ol>\r
353 <li>\r
354 <p>Retrieve release branch of the platform repository</p>\r
355 <pre><code>git clone ssh://&lt;user&gt;@www.simantics.org:29418/simantics/platform.git\r
356 cd platform\r
357 git branch release/x.y.z[.w] remotes/origin/release/x.y.z[.w]\r
358 git checkout release/x.y.z[.w]\r
359 </code></pre>\r
360 </li>\r
361 <li>\r
362 <p>Edit all target platform files in  <code>releng/org.simantics.sdk.build.targetdefinition/</code>, i.e.</p>\r
363 <ul>\r
364 <li><code>simantics.target</code></li>\r
365 <li><code>org.simantics.sdk.build.targetdefinition.target</code></li>\r
366 <li><code>org.simantics.sdk.build.targetdefinition-semantum.target</code></li>\r
367 </ul>\r
368 <p>At the beginning of each .target file, increment <code>sequenceNumber</code> by 1</p>\r
369 <pre><code>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;no&quot;?&gt;\r
370 &lt;?pde version=&quot;3.8&quot;?&gt;\r
371 &lt;target name=&quot;Simantics x.y.z[.w]&quot; sequenceNumber=&quot;11&quot;&gt;\r
372 </code></pre>\r
373 <p>Next, replace the following rows in those files:</p>\r
374 <pre><code>&lt;repository location=&quot;http://www.simantics.org/download/master/sdk&quot;/&gt;\r
375 &lt;repository location=&quot;http://www.simantics.org/download/master/external-components/maven&quot;/&gt;\r
376 &lt;repository location=&quot;http://www.simantics.org/download/master/external-components/manual&quot;/&gt;\r
377 </code></pre>\r
378 <p>with</p>\r
379 <pre><code>&lt;repository location=&quot;http://www.simantics.org/download/release/x.y.z[.w]/sdk&quot;/&gt;\r
380 &lt;repository location=&quot;http://www.simantics.org/download/release/x.y.z[.w]/external-components/maven&quot;/&gt;\r
381 &lt;repository location=&quot;http://www.simantics.org/download/release/x.y.z[.w]/external-components/manual&quot;/&gt;\r
382 </code></pre>\r
383 </li>\r
384 </ol>\r
385 <h3>Initialize release branch distribution web site</h3>\r
386 <ul>\r
387 <li>Run <a href="https://www.simantics.org/jenkins/job/SDK/job/Deploy%20External%20Components%20to%20Web/">SDK/Deploy External Components to Web</a> build with parameters:\r
388 <ul>\r
389 <li><strong>GERRIT_REFNAME:</strong> <code>release/x.y.z[.w]</code></li>\r
390 <li><strong>PUBLISH_ARTIFACTS:</strong> <code>true</code></li>\r
391 </ul>\r
392 </li>\r
393 <li>Run the <a href="https://www.simantics.org/jenkins/job/SDK/job/Simantics%20SDK/">SDK/Simantics SDK</a> build with parameters:\r
394 <ul>\r
395 <li><strong>GERRIT_REFNAME:</strong> <code>release/x.y.z[.w]</code></li>\r
396 <li><strong>PUBLISH_ARTIFACTS:</strong> <code>true</code></li>\r
397 </ul>\r
398 </li>\r
399 </ul>\r
400 <h2>Review documentation</h2>\r
401 <p>Documentation to review:</p>\r
402 <ul>\r
403 <li><a href="http://dev.simantics.org/">Developer wiki</a></li>\r
404 <li><a href="http://www.simantics.org/end_user_wiki">End-user wiki</a></li>\r
405 <li><a href="http://www.simantics.org/members">Member wiki</a></li>\r
406 </ul>\r
407 <p>For each wiki page:</p>\r
408 <ul>\r
409 <li>Read through and get authors to fix found problems, such as TODOs or invalid information.</li>\r
410 </ul>\r
411 <h2>Review tutorials</h2>\r
412 <ul>\r
413 <li>\r
414 <p>Ensure tutorial wiki documentation at http://dev.simantics.org/index.php/Tutorials is up-to-date with the released platform</p>\r
415 </li>\r
416 <li>\r
417 <p>Ensure tutorial projects and product build properly</p>\r
418 </li>\r
419 <li>\r
420 <p>com.acme.movie</p>\r
421 <ul>\r
422 <li>Build with Buckminster, com.acme.movie.product.site.feature</li>\r
423 </ul>\r
424 </li>\r
425 </ul>\r
426 <h2>Tag release/* branches</h2>\r
427 <p>When the release branches are ready for the release, tag them with the tag <code>vx.y.z[.w]</code>:</p>\r
428 <pre><code>git clone ssh://&lt;user&gt;@www.simantics.org:29418/simantics/platform.git\r
429 cd platform    \r
430 git checkout release/x.y.z[.w]\r
431 git tag vx.y.z[.w] -m &quot;Simantics x.y.z[.w] release&quot;\r
432 git push origin --tags\r
433 \r
434 git clone ssh://&lt;user&gt;@www.simantics.org:29418/simantics/third-party.git\r
435 cd third-party\r
436 git checkout release/x.y.z[.w]\r
437 git tag vx.y.z[.w] -m &quot;Simantics x.y.z[.w] release&quot;\r
438 git push origin --tags\r
439 </code></pre>\r
440 <blockquote>\r
441 <p>Note The -m argument must be supplied to create an <a href="https://git-scm.com/book/en/v2/Git-Basics-Tagging">annotated tag</a>.\r
442 Only annotated or signed tags can be pushed to Gerrit.</p>\r
443 </blockquote>\r
444 <h2>Tag documentation wikis</h2>\r
445 <p>Tag documentation wiki using <a href="./tag.sh">tag.sh</a> script.</p>\r
446 <p>The wiki documentation is mainly in MediaWiki installations. The only sane way to tag the documentation is to clone it:</p>\r
447 <ul>\r
448 <li>Copy the wiki installation from wiki to ${release_version}/wiki</li>\r
449 <li>Copy the trunk wiki MySQL database into a new version</li>\r
450 <li>Reconfigure the tagged wiki (LocalSettings.php) to use the copied database and no longer allow any edits</li>\r
451 </ul>\r
452 <h2>Compile change log entry</h2>\r
453 <ul>\r
454 <li>Edit the <a href="https://www.simantics.org/redmine/projects/simantics-platform/wiki/ChangeLog">main page</a> and add a a link for release x.y.z[.w].</li>\r
455 <li>Open the change log page of the previous release, e.g. <a href="https://www.simantics.org/redmine/projects/simantics-platform/wiki/Simantics_1250">1.25.0</a></li>\r
456 <li>Open the new link in another browser/tab to start editing the new wiki page</li>\r
457 <li>Edit the previous release's page and copy its wiki source contents over to the new release's page.</li>\r
458 <li>Fix the content to match the new release:\r
459 <ul>\r
460 <li>Remove the issue content of the previous release</li>\r
461 <li>Fix release number, release date, release branch link and the link to all issues closed for the release\r
462 <ul>\r
463 <li>Save new public issue query that lists all issues closed for the release by <a href="https://www.simantics.org/redmine/projects/simantics-platform/issues?query_id=122">starting from the previous release's query</a></li>\r
464 </ul>\r
465 </li>\r
466 <li>Add filter to query: <strong>Release Notes: Any</strong> to only show issues that have some content in their Release Notes field</li>\r
467 <li>Export closed issue list as CSV with selected columns only. Open the resulting CSV file in Excel.</li>\r
468 <li>Use <strong>Data -&gt; Text to Columns</strong> with tab column separation to columnize the result</li>\r
469 <li>Format the list as a table so that there is only one issue / row</li>\r
470 <li>Remove all other columns besides: Issue #, Tracker, Release Notes</li>\r
471 <li>Format the data into a Textile table:\r
472 <ul>\r
473 <li>Copy to table contents as text into <a href="http://www.pspad.com/">PSPad</a></li>\r
474 <li>Replace (CTRL+H) tabs (<code>\t</code>) with <code>|</code> with <code>Regular Expressions</code> selection checked</li>\r
475 <li>Use <strong>Insert Text Into Lines..</strong> (ALT-I) to fix line beginnings and ends:\r
476 <ul>\r
477 <li>Text:\r
478 <ul>\r
479 <li>At Lines Begin: <code>|#</code></li>\r
480 <li>At Lines End: <code>|</code></li>\r
481 </ul>\r
482 </li>\r
483 </ul>\r
484 </li>\r
485 </ul>\r
486 </li>\r
487 <li>Copy the resulting textile table over to the change log page</li>\r
488 </ul>\r
489 </li>\r
490 <li>Highlight major issues in the list by changing the text background color of the <strong>Type</strong> column:\r
491 <ul>\r
492 <li><code>%{background: lightsalmon}Major Bug%</code></li>\r
493 <li><code>%{background: lightgreen}Major Feature%</code></li>\r
494 <li><code>%{background: lightgreen}Major Enhancement%</code></li>\r
495 </ul>\r
496 </li>\r
497 </ul>\r
498 <h2>Disseminate information about the release</h2>\r
499 <ul>\r
500 <li><a href="https://www.simantics.org/redmine/">Redmine</a>: Post news on the developer/user-visible changes here.</li>\r
501 <li><a href="https://www.simantics.org">simantics.org</a>: Post news on the release and a link to the redmine post</li>\r
502 <li><a href="http://dev.simantics.org">dev wiki</a>: Update roadmap at http://dev.simantics.org/index.php/Roadmap</li>\r
503 <li><a href="mailto:simantics-developers@simantics.org">simantics-developers@simantics.org</a> Send mail to simantics-developers:</li>\r
504 </ul>\r
505 <p><strong>Mail template:</strong></p>\r
506 <pre><code>Hello everyone,\r
507    \r
508 Simantics release x.y.z[.w] has been released. Head over to\r
509 https://www.simantics.org/redmine/news/&lt;news number&gt;\r
510 for the release news.\r
511 \r
512 Best regards,\r
513 Simantics Release Engineering Team\r
514 </code></pre>\r
515 <p><strong>News entry template:</strong></p>\r
516 <pre><code>On &lt;date&gt; Simantics x.y.z[.w] was tagged in SVN. Please find change log at:\r
517 * [[simantics-platform:Simantics_xyzw|Simantics x.y.z.w]]\r
518 \r
519 Insert some general thoughts on the release...\r
520 </code></pre>\r
521 <hr />\r
522 <h1>TODO</h1>\r
523 <ul>\r
524 <li>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</li>\r
525 <li>Create a parametrized release train pipeline build in Jenkins that creates all artifacts of a simantics release in one go</li>\r
526 <li>Start using https://github.com/mbarbero/fr.obeo.releng.targetplatform to generate <code>.target</code> files. <code>.tpd</code> files allow specifying version ranges instead of specific versions.</li>\r
527 </ul>\r
528 \r
529 </body>\r
530 </html>\r
531 <!-- This document was created with MarkdownPad, the Markdown editor for Windows (http://markdownpad.com) -->\r