[Development] Branching for Qt 5 repositories

[Thiago Macieira]

Hello

A few weeks ago I met with Lars, João, Sinan, Sergio A., Jędrzej and a few 
others and we discussed the branching for the Qt 5 repositories. This, 
therefore, does not apply to Qt 4, which shall remain as it is. It does not 
apply to Creator either, but it is available for them to adopt it if they want 
to.

This follows João's 3-branch plan (the Firehose/Leaky Faucet/Dripping bucket 
one), but with more "traditional" branch names.

They are:
 - dev: unfrozen branch, containing alpha-quality[*] code that is ready to go
   into beta testing at any time
 - stable: feature-frozen branch, containing beta-quality or better code
 - release: deep-frozen branch, for which only the release team should 
   approve changes, containing code about to be released

[*] alpha quality is feature complete, working, documented, tested, etc.

Note that there is no "master" branch any more. In addition, the default 
branch  (the one that gets checked out on a new clone) will be either stable 
or release, but definitely not dev. The intention is that new developers who 
clone Qt repositories for the first time are presented with a stable codebase 
they can begin working on, bugfixing and even developing new features for.

Here's the transition plan:

1) [transition1.png] First, we'll branch dev from master. Master will be 
regularly merged into dev, as the current submissions in Gerrit are drained. 
New submissions should go straight into dev. Once the master branch is drained 
of reviews, it will be closed.

2) [transition2.png] The stable branch will branch off from dev. At this point, 
dev becomes unfrozen again, accepting new features for Qt 5.1. At a later date 
(or very soon after), releases is branched off from stable.

Note that the timing of 1 and 2 can be anything. In particular, it is probably 
a good idea to unfreeze dev *before* master is closed. That way, current WIP 
5.1 reviews in Gerrit can be submitted, instead of abandoned and re-pushed 
into dev later.

For the Qt 5.0 release, we will release from the correct branch (releases).

Timing-wise, we would like to see the dev branch open in mid-October. If the 
5.1 merge window is 6 months, this would put the 5.1 feature freeze in 
April/2013.

Here's how the "permanent regime" will be:

1) all three branches are permanent. They are never deleted. Only the versions 
that they target change.

2) [permanent1.png] all bugfixes go into the "most frozen" branch that they are 
relevant for, including new features (which of course go into dev). The 
branches are periodically merged, using the CI, from "most frozen" to "least 
frozen".

3) [permanent2.png] features trickle down along with version numbers. The Qt 
Project is the only entity allowed to assign Qt version numbers. Note that are 
always working on at least two minor versions at the same time, sometimes 
three. The feature freeze for a given release is when dev is merged into 
stable.
 Also note how the release names match the state of the branch: alpha from 
dev, beta from stable, releases from releases.

4) we'll follow a hybrid time- and quality-based schedule:
 - time-based: time between feature freezes (e.g., 6 months)
 - quality-based: maturation of a dot-oh release
 - hybrid: patch releases, should be released timely (e.g. every 2 months), 
   but never in worse quality than a previous release
   [in mid-Qt 4 times, we used to release patch-level releases every 6-8 weeks 
   and it usually took us 1 week from start to finish]

The period between feature freezes should be 6 months in the long-term. In the 
short term, it might be slightly less or slightly more, if the Qt Project 
wishes to, in order to align our releases with our downstreams.

5) the Qt Project will not maintain a Qt version before the one currently in 
the release branch. Other parties may provide maintenance if so they wish and 
the Qt Project should welcome those branches in its infrastructure, but the 
branches should not be in the main Qt repositories. Releases made out of 
those branches or others outside of the Qt Project should be clearly marked 
and should avoid taking confusing numbering. For example, a release could be 
the last official Qt version plus the number of commits applied on top, plus the 
company's name. (e.g., 5.2.2-digia-125)

6) the exception to the above are security or very critical fixes, which may be 
applied to previous releases, directly on top of an existing tag and 
triggering a new release. That is, if it's relevant enough that everyone 
should update, then there's no reason not to make that a Qt release. For 
example, with 4.7 now and the security fix that was released today, we should 
make a new Qt 4.7 release immediately and tag.

Thiago, reviewed by João

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
     Intel Sweden AB - Registration Number: 556189-6027
     Knarrarnäsgatan 15, 164 40 Kista, Stockholm, Sweden
-------------- next part --------------
A non-text attachment was scrubbed...
Name: transition1.png
Type: image/png
Size: 4511 bytes
Desc: not available
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120927/13b4a7ef/attachment.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: transition2.png
Type: image/png
Size: 6554 bytes
Desc: not available
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120927/13b4a7ef/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: permanent1.png
Type: image/png
Size: 17683 bytes
Desc: not available
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120927/13b4a7ef/attachment-0002.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: permanent2.png
Type: image/png
Size: 15812 bytes
Desc: not available
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120927/13b4a7ef/attachment-0003.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120927/13b4a7ef/attachment.sig>