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 | |
---|
8 | Release Process |
---|
9 | *************** |
---|
10 | |
---|
11 | The release process creates an RTEMS release. The process has a number of |
---|
12 | stages that happen before a release can be made, during the creation of the |
---|
13 | release and after the release has been made. |
---|
14 | |
---|
15 | Releases |
---|
16 | ======== |
---|
17 | |
---|
18 | RTEMS is released as a collection of ready to use source code and built |
---|
19 | documentation. Releases are publicly available on the RTEMS servers under |
---|
20 | https://ftp.rtems.org/pub/rtems/releases. |
---|
21 | |
---|
22 | Releases are group under the major version number as a collection of |
---|
23 | directories consisting of the version number. This is termed a release |
---|
24 | series. A release may also contain release snapshots. |
---|
25 | |
---|
26 | All releases must have a three digit version number and this can be optionally |
---|
27 | followed by a dash character (``-``) and an identifier, e.g. ``5.1.0-acme-1``. |
---|
28 | |
---|
29 | The RTEMS Project reserves releases with only the three digit version number, |
---|
30 | e.g. ``5.1.0``. This identifies an RTEMS Project release. |
---|
31 | |
---|
32 | Release 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 | |
---|
61 | Release Version Numbering |
---|
62 | ------------------------- |
---|
63 | |
---|
64 | The release numbering scheme changed with RTEMS 5. |
---|
65 | |
---|
66 | The master branch has the version N.0.0 with N being the next major release |
---|
67 | number. The release branch in a repository will be just the major number. |
---|
68 | |
---|
69 | The first release of this series will have the version number N.1.0. The first |
---|
70 | bugfix release (minor release) of this series will have the version number |
---|
71 | N.2.0. |
---|
72 | |
---|
73 | The release branch will have the version number N.M.1 with M being the last |
---|
74 | minor release of this series. Tools will use N as the version number and must |
---|
75 | be compatible with all releases and the release branch of the N series. |
---|
76 | |
---|
77 | Examples: |
---|
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 | |
---|
93 | Release 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 | |
---|
135 | Release 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 | |
---|
156 | Release Repositories |
---|
157 | ==================== |
---|
158 | |
---|
159 | The following are the repositories that a release effects. Any repository |
---|
160 | action 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 | |
---|
178 | Pre-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 | |
---|
187 | Release Branching |
---|
188 | ================= |
---|
189 | |
---|
190 | A release has a release branch in each of the release repositories. A |
---|
191 | release is a created from a release branch. The release branch label |
---|
192 | is the RTEMS major version number. |
---|
193 | |
---|
194 | LibBSD Release Branch |
---|
195 | --------------------- |
---|
196 | |
---|
197 | The ``rtems-libbsd.git`` is an exception as it has two active release |
---|
198 | branches. The repository has a release branch based on the ``master`` |
---|
199 | like all the release repositories and it can have a FreeBSD version |
---|
200 | specific release branch that is used in the release. |
---|
201 | |
---|
202 | LibBSD runs two branches during it's development cycle. The ``master`` |
---|
203 | branch tracks the FreeBSD ``master`` branch. This means LibBSD tracks |
---|
204 | FreeBSD's development. LibBSD also tracks a FreeBSD branch for the |
---|
205 | RTEMS release. For example RTEMS 5 tracks FreeBSD 12 as it's release |
---|
206 | base. This provides functionaly stability to the RTEMS 5 release by |
---|
207 | allowing a control process to track bug fixes in FreeBSD 12. |
---|
208 | |
---|
209 | Pre-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 | |
---|
226 | Branch 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 | |
---|
253 | Post-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 | |
---|
310 | Post-Branch Version Number Updates |
---|
311 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
312 | |
---|
313 | After the release repositored have been branched the ``master`` branch |
---|
314 | has to have the major version number updated. The follow is a list of |
---|
315 | the 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 | |
---|
352 | Release Procedure |
---|
353 | ================= |
---|
354 | |
---|
355 | The release procedure can be performed on any FreeBSD machine and uploaded to |
---|
356 | the 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 |
---|
358 | path 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 | |
---|
428 | Post-Release Procedure |
---|
429 | ====================== |
---|
430 | |
---|
431 | The 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. |
---|