Real-Time Robotics Framework

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Release Process ======

The following is a step-by-step procedure for releasing a new version of EEROS.

All the planning work is done on Trello on the **EEROS Tasks** Board. New developers have to request access rights by submitting the [[http://eeros.org/contact/|contact form]].

==== 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. 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:

  * Notes in the **description section**
    * The link to the CHANGELOG.md file
    * The targeted release date
    - **Release Notes** section
      * Description if it is a MAJOR or MINOR Release and why 
    - **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//).
The cards which are not in the **Done** list must either be relabelled with the label of the next version number or closed. The most reasonable solution is to comment the card and mention the responsible user by using the //@username// annotation.

This step should lead to a discussion on the card. The card members have to decide, if the code base is ready for the release or not. This step is finished as soon as all card members agree.

The steps 2-4 below can be done during the discussion phase since they will overlap with each other.


==== 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. 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 (v1.0 is used as an example):

<code>
git checkout -b v1.0 master
</code>

The new branch is pushed to the remote repository, which is the one on Github. The remote repository does not know the new branch yet. It can be set by the following git command: 

<code>
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>


==== 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 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.


==== 4. Stabilisation of the new release branch  ====

The new release branch must be stabilised. Intensive testing is now necessary. The Jenkins server helps during this phase by enabling various tests with different compilers and setups. If tests are necessary on specific hardware due to changes or new features, they are done in this step.

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. For this workaround, a Trello card must be filled and the issue resolved until the next release.


==== 5. Update the change log and create the release commit  ====

Before starting this step, steps 1-4 must be completed.

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:

  * Section for Added, Changed, Deprecated, Removed, Fixed, Security things.
  * Breaking Changes are listed separately (Changes changing the API and causing a MAJOR Release)
  * The latest version comes first
  * The release date of the Release
  * Link to GitHub compare feature which compares to the last release (show the changes)

The style should always match the previous entries and is base on [[https://keepachangelog.com/en/1.0.0/|this guidelines]].

The release branch is ready. The final commit must only contain changes in the **CHANGELOG.md** file.

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 *CHANGELOG.md*
git commit -m "Release v1.0.0"
git push
</code>


==== 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 release tag is created by completing the form, which can be reached via the following link:

https://github.com/eeros-project/eeros-framework/releases/new

It is very important, that the right release branch is selected. The form must be completed as shown in the picture below.

{{: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  ====

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 v1.0
</code>

 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
(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))

### Added Features
......
</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, 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$ make doc
</code>

The documentation can be found in **eeros-framework/buildFolder/doc/html**. It must be uploaded by the administrator to the EEROS Website.


==== 9. Creation of a new card to discuss suggestions for improvement  ====

This optional step provides the possibility to improve the release process. On the **EEROS Tasks** Trello Board, a new card is created in the list **General**. This card is filled with suggestions for improvement.