powered by Jive Software

Find a better way how we should version our software

Hi volks,

I want to discuss how we work with the main version and the development branch on github.

Actually Openfire is on version 3.9.2 and we’re working on a bugfix release 3.9.3. Some issue was raised in 3.9.2 that wasn’t part of 3.9.1. This is a bit annoying for the customers I think. if a version number changes on the last place, the “bugfix”-place, the customers don’t think that some issues are raised due new features.

I think many of us knew the version policy of apache maven: https://cwiki.apache.org/confluence/display/MAVEN/Version+number+policy

Today it’s really common and I think we should use it too.

But what does it mean for our development lifecycle? Currently we develop all our stuff on the master (or on branches that are merged into the master). The better way in my opinion is to branch direct of just a few days after the Major/Minor-Release. Then we shift the version on the master at the place of the minor-number - the branch gets a bugfix-version-number.

Improvements, Development, Bugfixes are directly integrated into the master. But the Bugfixes should be also merged into the latest bugfix-version.

For example:

We release 3.9 today. The master gets the version 3.10-alpha. All further development is integrated here. Also the bugfixes. (The master could be renamed later if the the next release needs a major number).

In parallel we create a branch for 3.9 and name it 3.9.1-alpha. To this tree we merge our bugfixes by merging or cherry-picking from other branches/commits.

Why we should do this?

Actually we’ve to touch the software with “velvet glove” because we’re waiting for the bugfix release 3.9.3. We can’t integrate a refactoring, I’ve really fear to provide some pull requests to the buildsystem that could break an assembly or something that I would test less.

That isn’t a complimentary ticket to break the build of the master or do refactorings with an axe! But I feel more comfortable with a real development branch where we could discuss the implementation and blame each other - regardless of our current bugfix release ;-D

Just my 2 cents,

Sven

I agree with you. The version numbering is uncommon, because new features and improvements were introduced in a bugfix release. It was also done in the past, although maybe not that extreme as in 3.9.2.

What you are saying is basically what is described in your link, but also in Semantic Versioning, which is a common and reasonable versioning.

Personally I am feeling very unfamiliar with git and don’t know how to manage multiple branches/tags + master and merging stuff between them, but it’s hopefully not that hard.

Personally I am feeling very unfamiliar with git and don’t know how to manage multiple branches/tags + master and merging stuff between them, but it’s hopefully not that hard.
That is exactly where git excels at.

Sven,

I think you are on the right track as well. In the past, we were desperate for bug fixes and new features, so beggars could not be choosers! In the present day, we have some momentum on github and more capacity to work at multiple branches.

Lets get 3.9.3 out the door today (I hope), then we/you can work to change how github repos are organized. Does this sound like a good idea?

daryl

Also I didn’t study Github in detail. I agree that after releasing 3.9.3 we should create a branch for 3.9.3 fixes foe issues indroduced in 3.9. No fixes / dev. of well-known issues should be commited there.

No idea why we should rename master to 3.10 or 4.

Maybe I should tell how it’s done in Smack:

The ‘master’ branch always contains the latest features and API changes. Once it has reached a stable state, a new release is tagged. It will be a Major release (e.g 4.0.0) if there are incompatible API changes and a Minor release (e.g. 4.1.0) if only new features have been added.

Once a bug is reported for a release, a release branch is created. For example a branch named ‘4.0’ from the ‘4.0.0’ tag. The bugfix is applied and once it’s determined that a new patch release should be relased it is tagged (e.g. ‘4.0.1’) and published.

The release branches (there could be more) get merged into the master branch (and into their following release branches, if such exists), to assure that it always contains the sum of all features and fixes. When this is done is up to the maintainer (usually after a patch release has been published, but maybe more often).

So release branches are only created when they are really needed.

Two more remarks about git: I prefer to avoid merge commits when possible. Sadly, github does not provide a mechanism to rebase branches. A pull request will always be merged. For Smack, I rebase pull requests and close the pull request manually (there was only one exception from this since Smack is on github).

Furthermore: Could you please aggree to always put the issue key into the commit message? And a issue, linked to a forum thread, should usually be created, even if it’s only a minor fix. I’m always created issues in Smack for fixes that affected released versions. Only if I change code that has not been released I don’t create an issue.

Sounds reasonable!

Let’s say you have a “long-living” bug like OF-241 and it would get fixed in the master during the course of normal development/process, e.g. for the 3.10 release. In the meanwhile there’s a need to release 3.9.5 due to some other bug.

Would you then also merge the bugfix for OF-241 from master to the 3.9.5 branch?

I have tagged 3.9.3 and not committed an updated version tag, so we have a clean slate at the moment. What shall happen now?

There is a 3.9.4 version in Jira, but it can just be a placeholder.

Let’s say you have a “long-living” bug like OF-241 and it would get fixed in the master during the course of normal development/process

Bugfixes, if they don’t cause incomptaible API changes, should usually always got into the oldest active release branch.

Would you then also merge the bugfix for OF-241 from master to the 3.9.5 branch?

It’s actually the other way around: The relase branches (e.g. ‘3.9’ in you example, note that there will never be a branch named ‘3.9.5’ only a tag) get merged into the master branch.

Here is a more complex scenario: Consider a release branch ‘3.9’, another release branch ‘3.10’ and the master branch. It was decided to create the ‘3.10’ branch because big fixes or new features where introduced that did not cause an API change, the ‘3.9’ branch contains some yet unreleased (usually) smaller bugfixes and the ‘master’ branch contains some new features that made an API change necessary.

A good example for an change that should go into the next feature release branch, ‘3.10’ in my example, is OF-103, which does introduce new functionality but does not change the API. Of course it is up to the dev to decide which branch to commit in. And we really shouldn’t ever have more then 3 active branches at the time:

  • one for bugfixes of the current release

  • one for new features

  • one for new features or changes that change the API or refactor/move source code

Usually you will end up with one ‘master’ branch, and only after a relase and if there are bugfixes you will have a release branch.

The advantage is also that you can publish bugfix releases (e.g. 3.10.2) relativly fast since the delta of commits between the previous release is small. And we could prepare -alpha, -beta, -rc releases for the current feature branch, which can be grabbed by the more adventerous users for testing purposes.

Probably as said in this thread: create a release branch “3.9” (from the 3.9.3 tag).

If there’s a need for a (fast) 3.9.4 bug fix release, the bug fixes can go into that branch.

In parallel the master branch can be used to move forward with new features/refactoring/Maven/Java 7/Tests (to be discussed).

For now, I have set the version of the master branch to 3.10.0-alpha. We can obviously tweek this going forward, but needed a new version to keep the bamboo builds happy. Yes, bamboo builds will need updated to reflect whatever development policy we come up with.