Differences

This shows you the differences between two versions of the page.

--- for_developers:releaseprocess [2019/01/16 00:08] – created kunz
+++ for_developers:releaseprocess [2024/12/18 11:33] (current) – [2. Creation of a new release branch] ursgraf
@@ Line 7: / Line 7: @@
 ==== 1. Announcement of a new release  ====
-On the **[[https://trello.com/b/9nLSxZ0B/eeros-tasks|EEROS Tasks]]** Trello Board, a new card must be created in the list **Releases**. It is recommended to use the copy function on the template card. The card must be named with the version name of the new release. EEROS is versioned according to the [[https://semver.org/|Semantic Versioning Specification]]. The card of the first major version as an example is named with v1.0.0.
+On the **[[https://trello.com/b/9nLSxZ0B/eeros-tasks|EEROS Tasks]]** Trello Board, a new card must be created in the list **Releases**. It is recommended to use the copy function on the template card. The card must be named with the version name of the new release. EEROS is versioned according to the [[https://semver.org/|Semantic Versioning Specification]]. The card of the first major version as an example is named with v1.0. Patches which are applied to a released version must be added to the corresponding card and the card name changed accordingly. For example, a patch for v1.0 is described in card v1.0 and the card name changed to v1.0.1.
 The card must be filled with the following information, which is also included in the template card:
-  - Release notes in the **description section**.
+  * Notes in the **description section**
-    - New features
+    * The link to the CHANGELOG.md file
-    - Bugfixes
+    * The targeted release date
-    - Other changes and improvements
+    - **Release Notes** section
-  - Checklist with at least the entries given in the template card.
+      * Description if it is a MAJOR or MINOR Release and why
-  - At least 3 board members must be added to the card.
+    - **Discussion Points** section
+      * List of point which must be discusses prior to the release
+    - **Issues to close before the Release** section
+      * List of issues to close before the release and links onto the corresponding card
+  * Checklist with at least the entries given in the template card
+  * At least 3 board members must be added to the card
 The next step is to go through all cards which are labelled with the version number of the new release. It is recommended to use the search functionality (for example search for all cards with label //Release 1.0// in list //General// => //#"Release 1.0" list:General//).
@@ Line 28: / Line 33: @@
 ==== 2. Creation of a new release branch  ====
-The EEROS release workflow supports multiple active releases. Therefore, every release is created on a release branch. The name of the release branch contains the //MAJOR.MINOR// part of the release number. The release tags contain the full pattern.
+The EEROS release workflow supports multiple active releases. Therefore, every release is created on a release branch. The name of the release branch contains the //MAJOR.MINOR// part of the release number. Only the release tags contain the full pattern.
-Since the development is done on the master branch, the release branch is created based on the HEAD of the master branch. The following git commands will create the new release branch (release/1.0 is used as an example):
+Since the development is done on the master branch, the release branch is created based on the HEAD of the master branch. The following git commands will create the new release branch (v1.0 is used as an example):
 <code>
-git checkout -b release/1.0 master
+git checkout -b v1.0 master
 </code>
@@ Line 39: / Line 44: @@
 <code>
-git push --set-upstream origin release/1.0
+git push --set-upstream origin v1.0
+</code>
+Probably you already have a release branch, e.g. do want to release v1.0.3 and still have your branch for v.1.0.2. If so, switch to branch v1.0 and **merge your master branch** (or whatever work you want to be included) into the release branch.
+<code>
+git checkout v1.0
+git merge master
 </code>
@@ Line 45: / Line 56: @@
 ==== 3. Creation of a new Jenkins item for the new release branch  ====
-After the creation of the new release branch, the code must be stabilised. Tests with different setups and compilers are the most of the time necessary. At least one item has to be added on the Jenkins server. How this is done is described on the //Creation of Jenkins item// page. This item must at least build EEROS with cmake and run all unit tests. An example is found //here//.
+After the creation of the new release branch, the code must be stabilised. Tests with different compilers are the most of the time necessary. At least one item must be added on the Jenkins server. This item must at least build EEROS with cmake and run all unit tests besides the tests of the HAL.
@@ Line 54: / Line 65: @@
 The API documentation is generated by Doxygen and must be fully inspected. Any changes made since the last release must be read and reviewed.
-If there are any issues, they must be fixed. If this is not possible without major changes, a workaround is implemented which will be resolved until the next release.
+If there are any issues, they must be fixed. If this is not possible without major changes, a workaround is implemented. For this workaround, a Trello card must be filled and the issue resolved until the next release.
-==== 5. Change version information and create a commit  ====
+==== 5. Update the change log and create the release commit  ====
 Before starting this step, steps 1-4 must be completed.
-The release branch is ready. The final commit must only contain the change of the version number in the main **CMakeLists.txt** file.
+In this step, the change log ([[https://github.com/eeros-project/eeros-framework/blob/v1.0/CHANGELOG.md|CHANGELOG.md]]) is updated and finalized. The change log must contain the following:
-The version information is changed as shown below (release v1.0.0 is used as an example).
+  * Section for Added, Changed, Deprecated, Removed, Fixed, Security things.
+  * Breaking Changes are listed separately (Changes changing the API and causing a MAJOR Release)
-<file>
+  * The latest version comes first
-.....
+  * The release date of the Release
-set(EEROS_VERSION_MAJOR 1)
+  * Link to GitHub compare feature which compares to the last release (show the changes)
-set(EEROS_VERSION_MINOR 0)
-set(EEROS_VERSION_PATCH 0)
+The style should always match the previous entries and is base on [[https://keepachangelog.com/en/1.0.0/|this guidelines]].
-set(EEROS_VERSION ${EEROS_VERSION_MAJOR}.${EEROS_VERSION_MINOR}.${EEROS_VERSION_PATCH})
-....
+The release branch is ready. The final commit must only contain changes in the **CHANGELOG.md** file.
-</file>
-Now, the change is committed and pushed to the EEROS repository on Github. The commit must contain the following message: **release/1.0.0**. This is done by the following git commands:
+Now, the change is committed and pushed to the EEROS repository on GitHub. The commit must contain the following commit message: **Release v1.0.0**. Of course, the right version number must be used. This is done by the following git commands:
 <code>
-git add *CMakeLists.txt*
+git add *CHANGELOG.md*
-git commit -m "release/1.0.0"
+git commit -m "Release v1.0.0"
 git push
 </code>
-==== 6. Publish the new release on Github  ====
+==== 6. Publish the new release on GitHub  ====
-The final commit was pushed to the repository on Github. It is important, that the release tag is set on the Github Website. Github provides a feature which will show special tags as releases.
+The final commit was pushed to the repository on GitHub. It is important, that the release tag is set on the GitHub Website. GitHub provides a feature which will show special tags as releases.
 The release tag is created by completing the form, which can be reached via the following link:
@@ Line 93: / Line 103: @@
 It is very important, that the right release branch is selected. The form must be completed as shown in the picture below.
-//insert picture//
+{{:for_developers:release_v1.0.0_github_1.png?nolink|}}
+Note that the information in the description section is copied from the change log.
 ==== 7. Merge the commits on the release branch into the master branch  ====
-Since there were new commit on the release branch only, they must be merged into the master branch. This ensures that the master contains all commits. This is achieved by the following git commands.
+The normal development was continued on the master during the creation of a new release. Since there were new commit on the release branch only during stabilisation phase, they must be merged back into the master branch. This ensures that the master contains all commits. This is achieved by the following git commands (example for release v1.0).
 <code>
 git checkout master
-git merge release/1.0
+git merge v1.0
 </code>
-The normal development is continued on the master during the creation of a new release. Since the new release is published, the current version on the master branch is now a snapshot of the next version. Therefore, the version information must be changed in the main **CMakeLists.txt** file as shown below (release v1.0.0 was released as an example).
+ Since the new release is published, the current version on the master branch is now a snapshot of the next version. Therefore, the **CHANGELOG.md** should contain a **Unreleased** section on the top. The developers than can add their changes to the change log during development.
 <file>
-.....
+## Unreleased
-set(EEROS_VERSION_MAJOR 1)
+(v1.1.0 targeted for 2019-06-30) ([Github compare v1.0.0...master](https://github.com/eeros-project/eeros-framework/compare/v1.0.0...master))
-set(EEROS_VERSION_MINOR 0)
-set(EEROS_VERSION_PATCH 0)
+### Added Features
-set(EEROS_VERSION ${EEROS_VERSION_MAJOR}.${EEROS_VERSION_MINOR}.${EEROS_VERSION_PATCH}-snapshot)
+......
-....
 </file>
 The change is committed and pushed.
+<code>
+git add *CHANGELOG.md*
+git commit -m "Add unreleased section"
+git push
+</code>
 ==== 8. Generate the API documentation with Doxygen  ====
-The second last step is to update the [[http://api.eeros.org/|API]] documentation on the EEROS Website. The HTML files are generated with Doxygen. The following command is issued, to start Doxygen:
+The second last step is to update the [[http://api.eeros.org/|API]] documentation on the EEROS Website. The HTML files are generated with Doxygen, which must be installed before the make script of EEROS runs. The following command on the release branch starts the process:
 <code>
-... eeros-framework/buildFolder$ doxygen Doxyfile
+... eeros-framework/buildFolder$ make doc
 </code>
-The documentation is found at the path //eeros-framework/buildFolder/doc/html//. The HTML documentation is uploaded as described below:
+The documentation can be found in **eeros-framework/buildFolder/doc/html**. It must be uploaded by the administrator to the EEROS Website.
-//describe upload.//
 ==== 9. Creation of a new card to discuss suggestions for improvement  ====