All software has bugs, and not all changes that you commit to a source tree are entirely good.
Therefore, some commits can be considered "development" (new features), and others can be considered "bugfixes" (redoing or sometimes undoing previous changes).
It can often be advantageous to separate the two: it is common practice to try and avoid mixing new code and bugfixes together in the same commit, often as a matter of project policy. This is because the fix can be important on its own, such as for applying critical bugfixes to stable releases without carrying along other unrelated changes.
Monotone, and other similar version control tools that utilise a DAG-structured revision history, offer developers an additional option to handle fixes in a way not possible (or at least, not convenient) in other tools with more linear history structures.
This page describes a BestPractices workflow pattern that uses the DAG structure, and the capability to easily diverge and re-merge from arbitrary past revisions, for advantage in handling fixes. It's an application of the same principles used by the ZipperMerge pattern, but for the scenario where you want to make the same change to two or more branches that must remain separate otherwise, rather than merge two branches together.
You have a project with a number of revisions and an existing graph that looks like this:
A | B / \ C D \ / E
It is later discovered that revision
B introduced a bug, and there's
a series of children
B->..->E that have inherited the bug from
(There could, of course, be many many intermediate revisions between
In monotone, we have two useful choices for how (or, more
specifically, where) to
commit the fix:
as a child of the current head,
as a direct child of the revision that introduced the problem,
mergethe two heads
Both produce a new head with the bug fixed, but they leave behind a different ancestry graph, and that difference can be important and useful.
The bug is fixed close to the point where development happened to be up to when it was found:
A | B / \ C D \ / E | F1
This is the common established practice in traditional sequential VCSs, in part because in those systems, branching and merging aren't lightweight enough to be worthwhile using for a small fix.
You might annotate the fix with some mention of
B in the changelog
as the bad revision being backed out or fixed, but that's usually as
far as it goes.
There's nothing really wrong with this (after all, it has worked for most software developers for a long time), but it represents a lost opportunity to use the power of monotone to full advantage.
The bug is fixed close to the point where it was introduced, and
A | B --+ / \ | C D F2 \ / | E | \ / M
There are good reasons to prefer this practice. This different graph structure gives you a strong and direct representation of the logical (rather than chrono-logical) relationship between bug, fix, and intermediate development:
You can see easily, in a tool like monotone-viz, the revisions containing the bug: all the revisions in the parallel path(s) spanned by
The fix is separated from other development as a direct part of the ancestry structure. Therefore, you can use the in-built merging tools of monotone, that understand how to work with this structure, to make sure the fix goes to other places that need it without confusion from other unrelated changes.
This reverses the common practice of "backporting" fixes to older code
(more on this below). Instead, the fix is developed against that
older code, and then ported forward as part of the
merge to the
This may also make the root cause of the error more apparent and thus easier to learn from, to avoid similar mistakes in future.
There are some variations on this theme that may be useful to consider:
Where the bug introduced in
Brepresents the entirety of the change
A->B, you may want
F2to completely undo the change.
For this specific case, monotone has the
disapprovecommand, which will internally create a new revision with the reverse diff as a child of
B(this command name is unfortunate, because it is not symmetrical with
In some rare cases where you want to redo
Bcompletely differently from scratch, you might want to
committhat as a child of
A(and sibling of
B) instead. You will then have to resolve any conflicts between the two alternate changes when you
This kind of pattern is most relevant for more fundamental changes than simple fixes, perhaps where the line of later development eventually leads to the conclusion that
Bwas a bad idea rather than a simple bug. This will usually involve an explicit named branch and several revisions for the parallel development path. You might even experiment with several variations before picking a winner.
For most cases, you just want to go back to
Band finish the original change properly. It's too late to fix the revisions that already inherited the incomplete or incorrect change, but you can
mergethe rest of the later development with the fix easily.
Many projects create release branches to track critical fixes to stable code while more active development goes on elsewhere. The important thing about a release branch, in this context, is that you want to separate fixes and development:
unlike a development branch, you don't intend to ever merge a release branch back with mainline (where it would eventually pick up the fix).
nor do you want to introduce arbitrary new developments from mainline to a release branch, wholesale.
Lets suppose, further to our example, that you had started a new
release branch from
D, midway along the span containing the bug:
A | B -----+ / \ | C D F2 \ / \ : E R1 : \ R2
You can immediately see that your release branch
inherited the bug, and is therefore also going to need the fix.
Even better, because
R2 have a common ancestor
introduced the bug), and
F2 contains only the fix for the bug,
F2 to that branch (and merging, as before) does
exactly the right thing, producing a fixed revision
RF on the
A | B ------+ / \ | C D F2 \ / \ : \ E R1 | : \ | R2 | \ | RF
Remember that monotone branch memberships are determined by certs, and branches need not be fully connected:
- After the
F2but before the
RF, the release branch contained disconnected revisions:
F2are still multiple heads of the branch, and a
mergecan succeed because of the common ancestor
Bis not a member of the branch.
F2 represents the true place of the fix in the graph and in both
branches, without introducing any of the other changes added in
E, or any other point past
D where the branch diverged.
If we had committed the fix the old way as
F1 instead, and tried to
approve like this, merging the release branch would pull in all
the changes from
E as well, just like a full
Although not drawn here, you can just as readily see that any other
branches which diverged above
B don't need a fix, because the bug
was introduced later.
If some of those were development branches that had
mainline to them, and some of those
then those branches would also need the fix.
This knowledge is the benefit of identifying
B as the source of the
bug, which you might have needed to do anyway regardless of where the
fix was applied.
Making sure to apply the daggy fix at
F2 means that you
automatically get the same benefit for knowledge of what has also
inherited the fix.
In general, any revision with
B as an ancestor and without
an ancestor, has inherited the bug but not the fix.
Remember that in distributed development with monotone, we might not
yet have learned about revisions descended from
B; in fact we might
never learn of someone else's private branch derived from
somewhere below B. We still want to publish the fix close to
that they can then
F2 for their private branch and
inherit the fix as well as the bug.
If you were to add a new test and testresult cert along with the fix
F2, it becomes even clearer where your fix has gone - especially
if your tool can colour the graph according to this ancestry or the
In many projects, the need to apply fixes to older revisions (especially releases) is addressed by applying patches containing the fix, sometimes adjusting or backporting for the older code. These fixes are taken from individual changes mixed with development along the mainline, and need to be separated out. This is often called CherryPicking, and is a frequent feature request for monotone. It's clear that many such requests are motivated by these kinds of concerns, especially from developers accustomed to these practices and familiar with support for similar features in other tools.
pluck can be used to pull the
set of changes between two (arbitrary) revisions "over there" into the
current workspace, taking into consideration other changes (like file
renames) that have happened between "there" and "here".
This allows isolated changes to jump across parts of the revision
graph, without making full ancestry connections in the same way that
propagate and similar commands would.
Doing Daggy fixes, as outlined above, will minimise the need to cherry-pick fixes instead. Daggy fixes mean using rather than losing the true origin and relationship between bugs and fixes in the ancestry graph. However, it's worth looking at some valid and recommended uses for this functionality, even in a project using Daggy Fixes.
Doing daggy fixes all the time isn't for everyone. It's not always so easy to develop a fix directly against the revision where the bug was introduced. Perhaps the bug wasn't discovered until some other more recent code used it in ways that exposed the bug; it would be hard to debug and find the fix without this other code around. Or perhaps the importance or scope of the fix simply hadn't been realised at the time.
So, continuing our scenario, assume the fix had been
directly as a new head,
E->F1, as in the first example.
Now, we've found that the bug originated in
B, and realised that the
fix will be needed on the release branch as well.
Or perhaps the bug was also found on the release branch, and traced
back to the common ancestor
B from there.
Either way, we can use the
pluck command to help us. Once again, we
have a couple of useful choices about where to
F1change straight across to the release branch, producing
R2->RFas a simple fix
commit, much like was done on the mainline head, with none of the structural benefits of daggy fixes.
or, now that we know better, it might be nice to go back up to
Band create the 'proper' daggy fix
F2, gaining the advantages outlined above for any other branches and descendants of
F2 is easy with
$ mtn co ... -r B . $ mtn pluck -r E -r F1 $ mtn commit
For simple fixes, this new
merge cleanly with
mainline, and with
R2 on the release branch as before.
For more intricate fixes, this step corresponds to backporting the fix
from mainline to the point of origin of the bug.
This makes it easier to
approve and then
merge that base fix
forward to other branches (which may have diverged since) as a
separate change, rather than attempting to adjust the change for both
development paths in the one step.
Attractive new features are developed on the mainline, and sometimes
it's desirable to add these new features to a stable branch, once it's
clear they are good.
However, we only want to bring the specific changes related to this
feature onto the release branch, and not all of the other unrelated
changes that would be carried along with it if we did a
If you can identify the list of changes that correspond to the
feature, you can
checkout a workspace on the stable branch, and
pluck each of these changes into it before committing. However,
doing so carries with it the responsibility to ensure that you find
all of the relevant changes -- including future changes that fix
bugs in the code you just
plucked. Because you've bypassed
recording the full origin of the changes in the DAG history, daggy
fixes won't work: you have to
pluck fixes for
features. Even then, daggy fixes are preferred: at least they're
easier to see because they're kept near the source revisions the
features were originally
Another example is where you've done a whole pile of development in a
private branch, but for one reason or another you really can't or don't
see the need to publish the whole gory history and internal working
details for a push into a more public repository.
pluck the entire span of the private development branch onto the
mainline, producing a single summarised change that rolls up all the
intermediate work and rework and rerework, showing only the