[kde-freebsd] Branching and merging in area51

[Adriaan de Groot]

[[ This afternoon, before messing around with some merges in area51, I wrote 
this down. I realise that it should be checked by more people -- and if it 
makes sense, I'd like to add it to the area51-documentation on f.k.o so that 
we've got a little documentation on the processes we try to follow. This 
message best viewed in fixed-font or pulled through markdown first. ]]

# Purpose of Area51 #

Area51 is where the KDE-FreeBSD (k-f) team works on ports infrastructure for 
the KDE packages (including Qt4, Qt5, KDE4, KDE Frameworks 5, Plasma 5, KDE 
Applications, Calligra, and supporting ports) without disturbing the official 
ports tree. The ports developed in area51 are committed to the official ports 
tree at irregular intervals, when some milestone has been reached.

The official ports tree is considered "downstream" from area51.

## Purpose of Branches ##

Branches in the area51 repository serve the purpose of defining milestones. A 
branch is used until the milestone is reached and the work is merged 
downstream -- for whichever definition of downstream applies to the branch.

One may also say that a branch represents a project: something with a definite 
goal in mind and a finite lifespan.

The one exception is trunk, which does not have a finite lifespan but 
regenerates, like a zombie, and carries on.

 - *trunk*  This is "what we want to get into ports next". It is a recurrent
   milestone, since there's always a next-big-thing. It sees fairly constant
   activity with taking over downstream (remember, that's the official ports
   tree) changes and in minor fixes. Some kind of "trunk slush" is in order
   to make sure that it's stable enough before a merge to downstream. (This
   actually refers to ^/trunk/area51 in the SVN repository)

   For trunk, the official ports are downstream, and branches are upstream.
   A release of trunk means committing all of its changes into the official
   ports tree.
 - *branches* These are particular projects for bigger updates that will
   eventually get to trunk. For example, the next Qt version, or the next
   Frameworks minor version, or a rearrangement of the infrastructure. 
   Branches are usually created off of trunk (rare cases might have a
   branch-off-a-branch). A branch has a purpose and some kind of 
   timeline attached. It is eventually merged into its downstream when
   its purpose has been achieved. While a branch is alive, it regularly
   merges changes that happen in its downstream (in so far as that makes
   sense: an update to a new port-X major version needn't take 
   patches from a previous version still downstream).

   For each branch, downstream is what it is created off of, so usually trunk.

Every change downstream should be acted on in some way -- even if that just 
means "ignore it, it will be made obsolete by this branch". That way changes 
and updates downstream don't get ahead of what we're working on.

When trunk is merged to its downstream (official ports), then we can have a 
release party or announce something has landed or whatever, and move on
to merging one of the branches to trunk again.


## Managing Merges ##

In principle, we've got three or more branches going on:

 - ports, the official ports tree,
 - trunk, our next-thing-to-commit,
 - branches, projects waiting in the queue.

Graphically, we get the following:


    ports   --------------------------------------------------------------->
                \1     \1             \1    /4                  /6
    trunk   --------------------------------------------------------------->
                             \2         \3    \3'     /5
    branch                    ------------------------
                            rNN         rNM           rMM
 
The official ports tree goes on and on. When something external changes the 
ports tree (e.g. fixes applied there directly by ports committers), those get 
merged to trunk (e.g. at points marked 1).

A branch to do something new (update portfrobnicator to 0.9) by splitting off 
from trunk, at point 2 (revision rNN in the area51 repo). Later changes to 
trunk (for instance caused externally, but could be part of general cleanup 
and other work on trunk) get merged to the branch (e.g. at point 3, revision 
rNM).

At some point, trunk is "done" and the exp-runs complete and trunk is 
committed to its downstream (i.e. the official ports tree) at point 4. Now 
trunk is momentarily "done", in the sense that there's no next-big-thing 
waiting to be finished. So we do some cleanup work, finish the update of 
portfrombicator, and merge that to trunk at point 5 with revision rMM.

Eventually the portfrobnicator update will also be merged, at point 6.

In this scheme, changes are merged upstream (ports -> trunk -> branch). When 
something is done, it gets merged downstream.

A consequence of this is that the svn:mergeinfo for trunk and for branches 
should be fairly simple:

 - a downstream shows no merges from upstream except when the upstream is 
   completed and gets merged in its entirety (e.g. point 5, when trunk 
   suddenly gets a merge of branch:rNN-rMM).
 - an upstream should show a contiguous range of merges from its downstream,
   to indicate that everything has been considered (and possibly ignored).
   At point 3, branch should show trunk:rNN-rNM, and just before point 5
   branch should show trunk:rNN-rMM (minus a few revisions) because it's been
   kept up-to-date with the downstream changes.

If we stick to this systematically, then merge-commands become quite simple:
 - branches do `svn merge ^/trunk/area51` (e.g. at point 3 and 3')
 - trunk does `svn merge ^/branches/branch` to wrap one up (e.g. at point 5)