source: rtems-docs/eng/release-process.rst @ 5bd15a0

Last change on this file since 5bd15a0 was 5bd15a0, checked in by Christian Mauderer <christian.mauderer@…>, on 07/29/20 at 09:13:28

eng/release: Add libbsd version update

  • Property mode set to 100644
File size: 13.3 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2020 Contemporary Software
4.. Copyright (C) 2020 Chris Johns
5
6.. _Release_Process:
7
8Release Process
9***************
10
11The release process creates an RTEMS release. The process has a number of
12stages that happen before a release can be made, during the creation of the
13release and after the release has been made.
14
15Releases
16========
17
18RTEMS is released as a collection of ready to use source code and built
19documentation. Releases are publicly available on the RTEMS servers under
20https://ftp.rtems.org/pub/rtems/releases.
21
22Releases are group under the major version number as a collection of
23directories consisting of the version number. This is termed a release
24series. A release may also contain release snapshots.
25
26All releases must have a three digit version number and this can be optionally
27followed by a dash character (``-``) and an identifier, e.g. ``5.1.0-acme-1``.
28
29The RTEMS Project reserves releases with only the three digit version number,
30e.g. ``5.1.0``. This identifies an RTEMS Project release.
31
32Release Layout
33--------------
34
35* All released source archives are XZ compressed tar files.
36
37* Top level contains:
38
39:file:`README.txt`:
40    A set of brief release instructions.
41
42:file:`contrib`:
43    Contributed sources. For example the release scripts used to create the
44    release.
45
46:file:`docs`:
47    Compressed documentation build in HTML, Single page HTML and PDF
48    formats. Provide compressed files for each document and a single archive
49    of all the documentation. Provide an SHA512 check sum file.
50
51:file:`rtems-<VERSION>-release-notes.pdf`:
52    RTEMS Release notes document the changes in a release. This is a capture
53    of the Trac report for the release's milestone in PDF format.
54
55:file:`sha512sum.txt`:
56    SHA512 checksum of all files in this directory.
57
58:file:`sources`:
59    All source code referenced by the release.
60
61Release Version Numbering
62-------------------------
63
64The release numbering scheme changed with RTEMS 5.
65
66The master branch has the version N.0.0 with N being the next major release
67number. The release branch in a repository will be just the major number.
68
69The first release of this series will have the version number N.1.0. The first
70bugfix release (minor release) of this series will have the version number
71N.2.0.
72
73The release branch will have the version number N.M.1 with M being the last
74minor release of this series. Tools will use N as the version number and must
75be compatible with all releases and the release branch of the N series.
76
77Examples:
78
79 - ``5.0.0`` is the version number of the development master for the 5 series
80
81 - ``5.1.0`` is the first release of the 5 series
82
83 - ``5.1.1`` is the version number of the 5 series release branch right after
84   the 5.1.0 release until 5.2.0 is released
85
86 - ``5.2.0`` is the first bugfix release of the 5 series
87
88 - ``5.2.1`` is the version number of the 5 series release branch right after
89   the 5.2.0 release until 5.3.0 is released
90
91 - ``6.0.0`` is the version number of the development master for the 6 series
92
93Release Scripts
94----------------
95
96* The release scripts are held in the top level repository
97  https://git.rtems.org/rtems-release.git.
98
99* The scripts are written for FreeBSD and can run on FreeBSD 10 through
100  FreeBSD 12. No other host operating system is supported for the release
101  scripts. Updates are welcome if the changes do not affect the operation on
102  FreeBSD.
103
104* A Python ``virutalenv`` environment is required for a working Sphinx
105  documentation building environment. Follow the procedure in the
106  ``rtems-docs.git`` top level ``README`` file.
107
108* Building a standard release requires you provide the release major number
109  and the release's remaining version string including any additional
110  identifiers:
111
112  .. code-block:: none
113
114     ./rtems-release 5 1.0
115
116  To create a release snapshot:
117
118  .. code-block:: none
119
120    ./rtems-release 5 0.0-m2003
121
122* A 3rd option of a release URL can be provided to create a test or deployable
123  release. The URL is a base path the RSB uses to download the release source
124  files from:
125
126  .. code-block:: none
127
128    ./rtems-release \
129        -u https://ftp.rtems.org/pub/rtems/people/chrisj/releases \
130        5 0.0-m2003-2
131
132* Building the release notes requires the Web Toolkit HTML to PDF converter be
133  installed. The FreeBSD package is ``wkhtmltopdf``.
134
135Release Snapshots
136-----------------
137
138* Release snapshots are only created for the current development version of
139  RTEMS. For example RTEMS 5 snapshot path is :file:`5/5.0.0/5.0.0-m2003`.
140
141* Release snapshots are based on the development sources and may be unstable or
142  not suitable for use in production.
143
144* A release snapshot is created each month and is named as
145  ``<major>/<version>/<version>-<YYMM>`` where ``YY`` is the last two digits of
146  the current year and ``MM`` is the month as a two digit number.
147
148* In the lead up to a release more than one snapshot can be created by
149  appending ``-<count>`` to the snapshot version string where ``<count>`` is
150  incremented starting from ``1``. The first snapshot without a count is
151  considered number ``0``.
152
153* Release snapshots maybe removed from the RTEMS servers at the discretion of
154  the RTEMS project
155
156Release Repositories
157====================
158
159The following are the repositories that a release effects. Any repository
160action is to be performed in the following repositories:
161
162#. ``rtems.git``
163
164#. ``rtems-docs.git``
165
166#. ``rtems-examples.git``
167
168#. ``rtems-libbsd.git``
169
170#. ``rtems-source-builder.git``
171
172#. ``rtems-tools.git``
173
174#. ``rtems_waf.git``
175
176#. ``rtems-release.git``
177
178Pre-Release Procedure
179=====================
180
181* All tickets must be resolved, closed or moved to a later
182  milestone. Tickets can exist that are specific to the branch and are
183  to be resolved before the first release is made.
184
185* Create release snapshots and post suitable build and test results.
186
187Release Branching
188=================
189
190A release has a release branch in each of the release repositories. A
191release is a created from a release branch. The release branch label
192is the RTEMS major version number.
193
194LibBSD Release Branch
195---------------------
196
197The ``rtems-libbsd.git`` is an exception as it has two active release
198branches. The repository has a release branch based on the ``master``
199like all the release repositories and it can have a FreeBSD version
200specific release branch that is used in the release.
201
202LibBSD runs two branches during it's development cycle. The ``master``
203branch tracks the FreeBSD ``master`` branch. This means LibBSD tracks
204FreeBSD's development. LibBSD also tracks a FreeBSD branch for the
205RTEMS release. For example RTEMS 5 tracks FreeBSD 12 as it's release
206base. This provides functionaly stability to the RTEMS 5 release by
207allowing a control process to track bug fixes in FreeBSD 12.
208
209Pre-Branch Procedure
210--------------------
211
212* All tickets assigned to the release's first milestone must be
213  resolved. Tickets can exist that are specific to the branch and are
214  to be resolved before the first release is made.
215
216* The following BSP must build using the RSB:
217
218  - ``arm/beagleboneblack``
219
220* Check and make sure the RSB kernel, libbsd and tools configurations
221  reference the ``master`` when the branch is made.
222
223  The RSB GIT builds reference a specific commit so it is important
224  the relevant configurations are valid.
225
226Branch Procedure
227----------------
228
229* Branch labels are the major number as branch releases increment the minor
230  number. A branch is only created when the first major release is made.
231
232  The commands to set a remote branch for a release in a repository are:
233
234  .. code-block:: none
235
236      git clone <URL>/<REPO> <REPO>
237      cd <REPO>
238      git checkout -b <VERSION> origin/master
239      git push origin <VERSION>
240
241  Example:
242
243  .. code-block:: none
244
245      git clone ssh://chrisj@dispatch.rtems.org/data/git/rtems.git rtems.git
246      cd rtems.git
247      git checkout -b 5 origin/master
248      git push origin 5
249
250* Check and make sure the RSB kernel, libbsd and tools reference the
251  branch commit.
252
253Post-Branch Procedure
254---------------------
255
256#. Create a release page for the next RTEMS release in Trac.
257
258#. Update the releases table. The page link is:
259
260     https://devel.rtems.org/wiki/Release
261
262   Update the table adding the new development release to the top
263   moving down the previous releases.
264
265   Label the new release branch as "Releasing". The documentation link
266   is left pointing to ``master`` until the release is made and the
267   documentation is installed on the RTEMS Documentation web site.
268
269#. Update the release table in the front page of the Trac Wiki. The
270   page link is:
271
272     https://devel.rtems.org/wiki/
273
274#. Add the milestones for the new development branch. The Trac page
275   is:
276
277  .. code-block:: none
278
279    = 6.1 (open)
280
281    == Statistics
282
283    ||   '''Total'''||[[TicketQuery(milestone=6.1,count)]]                                      ||
284    ||         Fixed||[[TicketQuery(status=closed&milestone=6.1,resolution=fixed,count,)]]      ||
285    ||       Invalid||[[TicketQuery(status=closed&milestone=6.1,resolution=invalid,count,)]]    ||
286    ||  Works for me||[[TicketQuery(status=closed&milestone=6.1,resolution=worksforme,count,)]] ||
287    ||     Duplicate||[[TicketQuery(status=closed&milestone=6.1,resolution=duplicate,count,)]]  ||
288    ||     Won't fix||[[TicketQuery(status=closed&milestone=6.1,resolution=wontfix,count,)]]    ||
289
290    == Distribution
291    [[TicketQuery(milestone=6.1&group=type,format=progress)]]
292
293    == Summary
294    [[TicketQuery(milestone=6.1)]]
295
296    == Details
297    [[TicketQuery(col=id|time|resolution|component|reporter|owner|changetime,status=closed&milestone=6.1,rows=summary|description,table)]]
298
299  Replace ``6.1`` with the required milestone.
300
301#. Create the RC1 release candidate with the source as close the
302   branch point as possible.
303
304#. Create a ticket to the clean the RSB for the release. The RSB's
305   ``master`` branch carries a number of older configurations and new
306   release configurations. These can be confusing to a new user and
307   add no value to a released RSB. For example leaving RTEMS 6 tool
308   building configurations in the RTEMS 5 release.
309
310Post-Branch Version Number Updates
311^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
312
313After the release repositored have been branched the ``master`` branch
314has to have the major version number updated. The follow is a list of
315the needed changes.
316
317#. RTEMS requires the following files be changed:
318
319    * :file:`aclocal/version.m4`
320
321    * :file:`c/src/aclocal/version.m4`
322
323    * :file:`cpukit/aclocal/version.m4`
324
325    * :file:`testsuites/aclocal/version.m4`
326
327    * :file:`rtems-bsps`
328
329#. RTEMS Documentation the following files be changed:
330
331    * :file:`wscript`: Update ``rtems_major_version``.
332
333#. RSB requires the following files be changed:
334
335    * :file:`source-builder/sb/version.py`: Update ``_version``.
336
337#. RTEMS Tools requires the following files be changed:
338
339    * :file:`config/rtems-version.ini`: Update ``revision``.
340
341    * :file:`tester/rtems/version.cfg`: Update ``rtems_version``.
342
343#. rtems_libbsd requires the following files and branches be changed:
344
345    * :file:`README.md`: Update ``Branches`` section.
346
347    * :file:`wscript`: Update ``rtems_version``.
348
349    * Create a new branch for tracking the FreeBSD stable version. E.g.
350      ``6-freebsd-12``.
351
352Release Procedure
353=================
354
355The release procedure can be performed on any FreeBSD machine and uploaded to
356the RTEMS FTP server. You will need ssh access to the RTEMS server
357``dispatch.rtems.org`` and suitable permissions to write into the FTP release
358path on the RTEMS server.
359
360#. The release process starts by branching the repositories. To branch
361   run the script:
362
363   .. code-block:: none
364
365       ./rtems-release-branch [-p] <USER> <VERSION> <REVISION>
366
367   Example:
368
369   .. code-block:: none
370
371       cd
372       mkdir -p development/rtems/releases
373       cd development/rtems/releases
374       git clone git://git.rtems.org/rtems-release.git rtems-release.git
375       cd rtems-release.git
376       ./rtems-release-branch -p chrisj 5
377
378   You need to have suitable commit access to the repositories.
379
380#. To create the RTEMS release run the release script:
381
382   .. code-block:: none
383
384       ./rtems-release <VERSION> <REVISION>
385
386   Example:
387
388   .. code-block:: none
389
390       ./rtems-release 5 1.0
391
392#. Copy the release to the RTEMS FTP server:
393
394   .. code-block:: none
395
396       ssh <user>@dispatch.rtems.org mkdir -p /data/ftp/pub/rtems/releases/<VERSION>
397       scp -r <VERSION>.<REVISION> <user>@dispatch.rtems.org:/data/ftp/pub/rtems/releases/<VERSION>/.
398
399   Example:
400
401   .. code-block:: none
402
403       ssh chrisj@dispatch.rtems.org mkdir -p /data/ftp/pub/rtems/releases/5
404       scp -r 5.1.0 chrisj@dispatch.rtems.org:/data/ftp/pub/rtems/releases/5/.
405
406#. Verify the release has been uploaded by checking the link:
407
408   https://ftp.rtems.org/pub/rtems/releases/<VERSION>/<VERSION>.<REVISION>
409
410#. Tag the release repositories with the following command:
411
412   .. code-block:: none
413
414       git checkout -b origin/<VERSION>
415       git tag <TAG>
416       git push origin <TAG>
417
418   Example:
419
420   .. code-block:: none
421
422      git clone ssh://chrisj@dispatch.rtems.org/data/git/rtems.git rtems.git
423      cd rtems.git
424      git checkout -b origin/5
425      git tag 5.1.0
426      git push origin 5.1.0
427
428Post-Release Procedure
429======================
430
431The following procedures are performed after a release has been created.
432
433#. Update the release to the RTEMS servers:
434
435   .. code-block:: none
436
437     rsync --rsh=ssh -arv 5.1.0 chrisj@dispatch.rtems.org:/data/ftp/pub/rtems/releases/5/.
438
439#. Test a build of the ``beagleboneblack`` BSP.
Note: See TracBrowser for help on using the repository browser.