nim-wiki/Official-branches.md

Official branches

This is a Work In Progress. Discuss on the IRC channel.

There are two official branches: stable and devel. The stable branch is a public facing branch which only contains whatever has been publicly released as a zip/exe/installer/whatever and linked from http://nimrod-lang.org/download.html. The purpose of the stable branch is being able to react to environment changes outside of the normal development cycle. By keeping an untainted source code branch hotfixes can be issued if necessary.

The devel branch is a development branch where code scheduled for the next stable is scheduled. Code not meant to be in the next stable release should be put in a third branch, named at will by the developer in charge of it. During normal development, code is added to devel, and contributors make pull requests based off of devel.

When a hotfix has to be issued, a branch is created off of the stable branch, necessary commits are added to it, and then it is merged into stable to be released publicly (or maybe after a delay to allow other possible hotfixes to go in that maintenance release) after tagging. Then the stable branch is merged into devel so that the hotfix is carried over.

When a normal release is to be done, devel is merged into stable and tagged with the release version.

Usage cases

The stable branch doesn't exist yet. For the purposes of these examples please run the following commands to create it:

$ git checkout v0.9.2
$ git checkout -b stable

In the future, stable will be the current master.

Quick web update

Let's suppose the web, which is generated through koch web needs updating but devel already contains new files or updated APIs and thus running koch web in devel would create the wrong stable documentation. First create a hotfix branch based off of stable:

$ git checkout stable
$ git checkout -b hotfix_web_udpate_750

Now, commit to this branch the necessary changes. In this case we have the change already on devel, so we can run:

$ git cherry-pick 814e441341245f7a7105c426cf6edcf3aa0edd78

Presumably this is all we need, so merge the hotfix branch into stable and tag for release.

$ git checkout stable
$ git merge hotfix_web_update_750
$ git branch -d hotfix_web_update_750
$ git tag vX.X.X

Don't forget to merge back into devel:

$ git checkout devel
$ git merge stable

Even in this case where you have picked commits form devel it makes sense for git, it will record and empty merge with the metadata saying both branches contain the same change despite their hashes being different. This helps in the future for the merge of the stable release.

Normal release

The normal release is easy:

$ git checkout stable
$ git merge devel
$ git tag vX.X.X

And development continues in devel.