Nut/OS Version Control
Software development for Ethernut uses CVS for revision control. So every file has a recorded history, which is stored in the CVS repository. The Ethernut CVS repository is hosted at Sourceforge and can be freely accessed by developers and users to retrieve the latest updates. In general, users don't need to understand the details about using CVS.
Nut/OS version numbers are devided into four parts separated by dots. Only the first three numbers are significant for official releases.
Major version number
This number will be incremented on releases with significant new features and general changes. Most probably existing applications need to be modified when the system is upgraded to new major version. Previously deprecated function may have disappeared.
Minor version number
Changes in the minor version number indicate possible incompatibilities to previous releases and may break existing applications. In fact, most official releases will appear with a new minor version numbers. Functions may become deprecated, but are still supported in new minor versions. Starting with version 3.4, Nut/OS uses even minor version numbers to mark stable, and odd numbers to mark unstable versions. Pre-releases of new major versions get a minor version number of 99.
Most Nut/OS users will not directly access the CVS repository, but prefer to use released packages. The release number is used to distinguish packages with bugfixes or minor changes. Full compatibility is guaranteed among different releases of the same major and minor version. Release candidates of new minor and major versions get a release number of 99.
This last number is for internal use and will not be part of released version. It may be used in the development process to distinguish intermediate steps.
Since version 3.4, Nut/OS uses branches to cut releases from the main development process. CVS tags are used to divide the development stream into different trunks. Instead of using the main trunk directly, a trunk is created first and this trunk is used for the official release. The advantage is, that bugfixes can be later applied to previously released versions without disturbing the main development process.
As an exception to the above rule, a new trunk will be created for special developments like porting to other compilers. Such work may introduce too many conflicts with the ongoing development. Thus, the task is simplified if done in a separate branch. In a final stage this branch will be merged to the main trunk again.
Most bugfixes will have to be applied to the main trunk as well as the latest release trunk. If, in rare cases, the related patches are substantial, it may make sense to apply them to the main trunk and merge them with the release trunk later.
You don't need to be a C, RTOS or network guru to become involved in the Nut/OS development process. Any help is most welcome.
In the first place it is highly recommended to subcribe to the Ethernut mailing list. This is the best place to report bugs and discuss fixes or enhancements.
Like with most Open Source projects, contributors will have different roles. In the Nut/OS development team, three different roles are specified: Release manager, developer and user.
The User's Role
This is probably the largest group and anybody, who downloads, installs and tries Nut/OS is automatically a user.
Every user is granted read and write access to the mailing list as well as anonymous read access to the CVS repository. However, to contribute there is no CVS access required at all. Users may simply present their ideas or report bugs in the mailing list, based on the official releases. In order to enable users without CVS to get their hands on the latest code, regular tarballs will be published in the future. Last not least, users can browse the entire repository with a Webbrowser.
More advanced users may post patches to the mailing list, where a developer may pick it up and add it to the recent code in the CVS repository.
The Developer's Role
Experienced users may apply for a developer's role by posting a request to the mailing list. If the request is granted, the user will receive write access to the repository and thus become a developer.
Developers implement new features and enhancements directly in the main CVS trunk. When the release manager announces a date of a release candidate branch, the developers are responsible to get the main branch to a stable state. They should not wait for the occurence of the branch.
After the occurence of the release candidate branch has been announced in the mailing list, the developers should intensely test that branch and make sure, that all discovered bugs are fixed. During this process developers can continue working on the main trunk. It is not required to keep the main trunk stable after the branch had been tagged. However, there may be fixes for the release candidate, which may also apply to the main trunk. In order to not disturb the work on either branch, these patches will be applied to both trunks.
In such rare case, where substantial fixes are required, a developer may decide to change the main trunk and later merge the changed files to the release trunk. However, it is a good idea to freeze any other development on the main trunk until the final merge occured.
The Release Manager's Role
Like developers, the release manager has write access to the CVS repository. In addition he coordinates all release activities, using the mailing list to announce upcoming events and publish completed tasks.
The release manager will change the release number in the main trunk to 99 and announce a date for a new release candidate branch in the mailing list. At that date he will tag the main trunk with nut-X_Y-branchpoint and branch the main trunk with the tag nut-X_Y_1-branch, where x is the major and y the minor version number. The release manager will announce in the mailing list when the branch has occured.
Developers and users assist the release manager by reviewing and testing the code of the release candidate and proposing updates. Developers will commit the fixes. After the release manager is satisfied and convinced, that the release candidate is stable, he will roll out an official release.
In critical situations the release manager may instruct the developers to limit the work on the main trunk for a certain period.
Creating a Branch
The following chapter is based on the hints and tips kindly provided by Ted Roth. He also documented the avr-libc release methodology in the avr-libc user's manual at www.nongnu.org
As described above, the release manager will create branches for release candidates. For releases, he cuts a branch for the release. The only changes allowed on the release branch are fixes, which had been already applied to main trunk.
Also developers, who intend to do more invasive changes may use private branches for this, since the main trunk is considered mostly stable. In this case it's up to the developer to pull fixes from head into his branch and once he feels the branch is ready, merge it back onto head.
The following steps are used by the release manager to create a branch of a new release candidate.
Update OS_VERSION_NUMBER and os_version_string in os/version.c by changing the release number to 99. Do the same for the AC_INIT entry in configure.ac. Log these changes in the ChangeLog file and commit these changes:
cvs commit -m "Release branch X.Y announced" os/version.c configure.ac ChangeLog
Announce the upcoming release branch in the mailing list.
Make sure that all developers are working towards a stable release in the main trunk. As far as possible all known bugs should be fixed until the release date announced in the mailing list.
At the announced date check out a clean source tree from CVS HEAD trunk:
cvs co nut
The release number of this version has been previously set to 99.
Set the branchpoint tag, replacing X with the major and Y with the minor version number of the upcoming release:
cvs tag nut-X_Y-branchpoint
The minor version number should be an even value. The tag will apply to the HEAD and can be later used to restore the situation immediately before the branch had been created.
Create the branch, again replacing X and Y accordingly:
cvs tag -b nut-X_Y-branch
Update OS_VERSION_NUMBER and os_version_string in os/version.c. The minor version should be set to the next odd value and the release and build numbers should be set to zero. Commit this file to CVS HEAD:
cvs commit -m "Release branch X.Y created" os/version.c
Note: Since Nut/OS is autoconfiscated, also configure.ac needs to be updated. Any other files?
Check out a new tree for the branch:
cvs co -r nut-X_Y-branch nut
Update OS_VERSION_NUMBER and os_version_string in os/version.c. Make sure to set the minor version number to an even value and the release and build numbers to zero. Commit this file to the release branch:
cvs commit -m "Release branch X.Y created" os/version.c
As stated in the note above, more files may require changing the version number.
Announce the branch and the branch tag to the mailing list so other users and developers can checkout the branch.
Creating a Release
A stable release will only be done on a branch, not from the main trunk.
Make sure the source tree you are working from is on the correct branch:
cvs update -r nut-X_Y-branch
More is required to create a source release for Linux and Windows.