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 contact form.
On the 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 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:
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.
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):
git checkout -b v1.0 master
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:
git push --set-upstream origin v1.0
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.
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.
Before starting this step, steps 1-4 must be completed.
In this step, the change log (CHANGELOG.md) is updated and finalized. The change log must contain the following:
The style should always match the previous entries and is base on 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:
git add *CHANGELOG.md* git commit -m "Release v1.0.0" git push
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:
It is very important, that the right release branch is selected. The form must be completed as shown in the picture below.
Note that the information in the description section is copied from the change log.
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).
git checkout master git merge v1.0
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.
## 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 ......
The change is committed and pushed.
The second last step is to update the 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:
... eeros-framework/buildFolder$ make doc
The documentation can be found in eeros-framework/buildFolder/doc/html. It must be uploaded by the administrator to the EEROS Website.
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.