Hi all,
I said I would try and outline where I think we should be in terms of moving
to git. I have to say that I am surprised at just how sudden such a switch
has taken place; in the past I had asked Jason and Dominik off-list what
would be involved, and whether it was a good idea. Reaction from both of
them was largely positive, and I think for different reasons. As I see it:
* Git is distributed; hence it completely removes most burdens on Jason who
currently maintains the entire CVS tree.
* We can still emulate CVS in terms of having an "official" central
repository which we consider to be "FVWM" itself.
* Git allows for off-line working; there is no requirement to be tied to a
central server for operations (such as "diff"). Hence there is no "single
point of failure".
* The checked out sources are *considerably* smaller than CVS - by an order
of magnitude with some projects, depending on how big the project is.
The big winner for me personally is this though:
* We help Jason out by removing the burden of CVS;
* Development is *much* simpler with git, as branches are cheap.
I don't really want to start a git advocacy thread here -- there's any
number of references [1] you can go and read up about git. But for me, when
I am working in CVS, I have a hard time separating out patch hunks to the
same file, where they introduce two completely different things. This is a
nightmare as CVS is file-based it more-or-less encourages this way of
working. Thankfully git does not. As branches are *encouraged* and cheap,
and hence merging is a joy as a result, one can have many different
development tracks on different branches, and never the twain shall meet.
I'm deliberately going to skip a git primer here as part of this -- if
people want more detail about how to use git specifically, you can always
ask me, and I'll do my best -- I don't mind, whatever people are comfortable
with. Just let me know.
[... Insert requisite knowledge of Git's features ...]
Workflow Ideas
==============
Git's default branch is called "master" -- in my git clone of FVWM [2] this
has all of the work done on 2.5.X -- what was "unstable". 2.4.X is there as
well, just tagged from CVS. I did not bother adding it as a separate
branch.
If we assume for a moment that 2.6.X and 2.7.X are synonymous (which
thankfully they are now!) then I would like to say upfront before I get too
knee-deep in my ASCII diagrams [3] quite loudly in fact, the following:
* 2.7.X DOES NOT EXIST IN FVWM. THERE IS NO LONGER A LONG-RUNNING
CONCEPT OF "UNSTABLE" AS HAPPENED WITH 2.5.X *
This is *key*, because git allows for branching, all 2.7.X could *ever* be
is nothing more than a collection of topics; different areas of working.
This is really important, because we had a massive fork between 2.4.X and
2.5.X (2.6.1, if you will) which meant no one was interested in updating
2.4.X because it was too much bloody effort [4]. So again, if we say the
following (not so loudly this time):
* 2.6.1's code becomes the basis of future development work. *
Then any development that takes place, etc., can just be released
incrementally on top of 2.6.X's code-base. We'll be forever more releasing
stable releases.
I can't stress this enough -- and I am sure I am preaching to the wrong
choir about this, in which case I apologise, but if I don't state things
clearly (and in this case loudly) then we'll be forever more in the wake of
2.6.X being the new 2.4.X, and I don't want that.
So how would development work? Well, let me draw a diagram:
o--o--o--o--o--o--o--o--o (ta/titleformat)
/
o--o--o--o--o--o--o--o--o (master)
\
o--o--o (de/colour-limiting)
Each "o" represents a commit. The "--"s indicate time passing between
them.
Here, "master" is the main branch, the stablest code we have, and it is the
branch on which all releases happen. Off it, at varying points people
might decide they want to write some cool new feature, or fix a bug. They
can do that, on a new branch, which they name. Such branches in Git have a
name, they're called "topic branches" -- they're designed to do one thing,
hold a topic of development [5].
In this case, at some point in master's history, I've created a branch off
it called "ta/titleformat". This branch is completely local to me, no one
else but me sees it because git is a sandbox environment. I can do what I
like in my own git repository until I make such a branch more "public" --
more on that later.
I've developed this topic and at various points through it, I commit changes
I've done, incrementally. Remember that git is changeset-based, so to that
end, I might have several commits which do the following:
* Introduce new .h or .c files.
* Update a Makefile to include them at compilation.
* Commits to add in logical changes to form sub features.
And you're allowed to do that with git. Git will let you apply chunks of
changes over time, and not the entire file, unlike CVS. This makes for a
much finer-grained history of changes over time, which is really useful when
tracking down bugs (more about that later on as well).
Obviously, as indicated other people in their own repositories might have
other branches they're working on as well.
Making such topic branches "public" for review/testing
======================================================
I said earlier that "master" was the canonical branch off which we release
updates and do development. But how then do we allow people to review
and/or test their features with other people involved?
The one thing we *CANNOT* do is merge to master here as that then means
we're happy to release it and an update is imminent. But we have some
options available:
1. Publish the branch -- push it to the "central/canonical" FVWM repository
so that other developers can see it, look at it, etc.
2. Create a patch series using "git format-patch" to create a series of
patches from the commits on a different branch.
3. Issue a "git request-pull" for a branch which sits on some other git
repository (perhaps Github?)
1., would seem like the most easiest answer, except that it quickly becomes
unmanageable as you end up polluting the git tree with a plethora of topic
branches. In some cases though this might be exactly what's needed if
developers want to collaborate on a given topic feature, although there's
other ways around that.
2., is slightly easier for peer-review, as by the time the patches are sent
out, there's some guarantee they're at least feature complete -- this also
means a maintainer can apply the patches on a local branch in their own
repository, do a bunch of work on top, and email out a proposed "v2" update,
etc., without having to then keep updating a git branch.
3., a more git-centric approach to what 2., brings. But still useful.
(This has the overhead of knowing about git remotes though, so I'm going to
skip this detail for now. It's academic anyway to having to use git.
I personally don't mind 1., above, if the number of branches are small, and
well-maintained. Because at some point, once a given feature is developed,
and tested in isolation on that branch, it will get merged to another
branch. Let's call it "next". The branch "next" is always rewound off the
HEAD of master at each release, and will form a "here's what I'm planning to
merge to master for release" branch. It might look like this:
o--o--o--o--o--o--o--o--o--o--o--o--o--o--o (master)
\ \
\ o--o--o--o--o--o--o (next)
o--o--o--o--o-------------------------/ (ta/titleformat merged)
Where my ta/titleformat branch is merged into next, along with other
proposed topic branches we might want in a next release. If we decide at
this point that actually one of the topic branches in "next" sucks, or we
don't/can't use it just yet, or it gets a "C-, not good enough tadam, see me
after" score from DV, then we can just drop it from next, and forget it was
ever there. Then we can merge next into master, and tag the branch as the
next version and do all the usual release-type things we used to with CVS.
Bug-fixing can happen in a similar way, but instead of "next", there might
be a "maint" branch kicking about which does something similar.
The point I'm getting at here, and I hope it's an obvious one, is that no
one does *any* work directly on top of "master" or "next" or "maint", or
anything that's meant to be a means to an end. That way, with things being
in topic branches, every branch that's going to be long-lived serves a
direct purposes. Topic branches may well come and go over time, that's
expected as they're either merged into master (by way of "next") or simply
deleted.
One question I often get asked a lot, is: "What happens to my topic branch
over time, as it gets older and older, and there's been updates to master
which will likely cause conflict, etc." This is a very classic CVS way of
working (some of my colleagues at work even go back as far as using SCCS.
:P) The whole point of your topic branch is that it details one specific
feature. As soon as the instinct of: "I'll just merge in master to get the
latest and greatest changes" happens, think about your topic branch -- it
now contains a plethora of useless changes which have nothing to do with
your feature anymore.
Yes, you're bound to run into bugs as a result which may well have been
fixed in later commits on a different branch, but that's OK -- you're only
interested in your feature. What I do in this situation (especially at
work):
# Get the latest and greatest work.
% git checkout -b test-master master
# Merge the topic branch to date.
% git merge ta/titleformat
[... test, test, test ...]
Then I end up seeing what things are like, and deleting the branch:
% git branch -D test-master
Of course, the above is just a form of "quick peek and see" -- integration
points I'm suggesting above by way of "next", "master", and "maint" obviate
the need for this quick check over time.
Of course, by publishing these branches, "next", "maint", etc., anyone
cloning our "official" FVWM repository and doing work in it can also follow
the same pattern themselves -- this makes it easier for external
collaborators to fix up patches on to of existing topic branches in "next"
for example.
Which is the point I was perhaps trying to make earlier -- by not publishing
every topic branch people are working on, but instead having them referenced
in an integration branch, such as "next", resurrecting these branches for
further development, to apply patches in top of them, etc., becomes possible
-- especially in the case of point 2., above with people sending out patch
series, etc. I can expand upon the git mechanics of this in time, if
reminded to do so.
Quis Custodiet Ipsos Custodes?
=============================
What happens to the people controlling this -- I mean, at the moment, we
have a group of people on fvwm-workers doing maintenance, etc., and that has
to continue. The nice thing about git for this is that it becomes a much
more social issue than it does technical -- git relies on good communication
and social management to work at its peak.
With a workflow defined above, this forms a nice redundancy barrier like we
have at the moment where people come and go, and there's no one central
point of failure from any one person. With CVS and having one tree with a
bunch of commits, separating out mistakes on FVWM's unstable branch would
have sucked.
Likewise for review, or for release, someone (seemingly at the moment
myself, but see above., I could drop dead next week) still has to keep track
of this though -- and I don't mind continuing doing this, assuming people
are happy for that. I appreciate I've made a few gaffs with the 2.6.X
releases though. Hopefully a new work-flow will mitigate those. Ahem.
Making a Release
================
I alluded to this above. But a release now should hopefully be a lot
easier, if only because what's in docs/DEVELOPERS is somewhat reduced in
complexity.
When we merge "next" or "maint" to "master", we need only to change
configure.ac as we have been. We can simplify the "make distcheck2" stage
by tagging the tree at that point (c.f. with what CVS does in terms of
tagging -- although in git terms, it's not tagging files, it's tagging a
point in *time*) and using "git archive" to do all of the work for us.
Hopefully with things like gitosis, it will allow me and others to put
tarballs ourselves in place, for a release, hopefully making Jason's life
easier, as currently he's a potential bottle neck in the release process,
although he does a sterling job at being bloody quick in getting tarballs
published. :)
What happens next?
==================
Assuming *any* of the above is feasible then we need to decide at a
high-level the following (in no particular order):
* Moving fvwm-web into its own git repository
* Look at the scripts in fvwm-web which make massive assumptions about CVS.
* Update the configure.ac file which likewise assumes CVS.
* Think about what to do about fvwm-config -- again, makes CVS assumptions.
* In terms of fvwm-web, there won't *be* an unstable release per-se -- how
does this affect the PHP code, with links, scripts to automate things,
etc?
* docs/DEVELOPER-CVS must be replaced.
* fvwm-web must be updated to remove any mention of CVS, and equivalent
pages must be put in place.
And finally...
==============
I'm more than happy to do the work for this -- it's more or less already
been done with the FVWM git repository being present, the rest of it is
house-keeping, which will take a fair amount of work, but I don't mind that.
We can do it incrementally and in stages, it's not a suggestion from me that
we do everything at once, in one go -- we have to move away from that
concept.
I know I've skipped over many things, but I've tried to give a birds-eye
view of how I think we can fit git into this, rather than getting
bogged-down in git terminology, etc. Obviously I might have to in the
future.
So -- any questions, thoughts, etc., just ask.
Kindly,
-- Thomas Adam
[1] http://www.git-scm.com
[2] https://github.com/ThomasAdam/fvwm
[3] Sorry guys, I am no Cezanne, I warn you...
[4] In England, terms like "bloody" and "damn" aren't considered as
blasphemous anymore -- and neither does my use of them signify any kind
of excitement on my part. :)
[5] This is conceptual though -- people can commit any thing they like to
a branch, but having a clear separation of concerns is handy.
--
"It was the cruelest game I've ever played and it's played inside my head."
-- "Hush The Warmth", Gorky's Zygotic Mynci.
