Toward a better release and development cycle (LONG, README)

[ Disclaimer: this has been written in CDG airport Terminal F while
waiting for my return flight ]

Hi,

AbiWord 2.2 is soon to be release thanks to the joint effort of all the
developers and contributors, thank you to all.
But, I think we could have do better in less time if we had followed
some rules, that with the experience we now have, we should try to
establish and follow. Basically, we lost a lot of time and effort
maintaining 2.0.x while developping 2.2. Maintaining these 2 branches
was and will still be a requirement, but I wish that it would cost us
less.

I'll try to explain as much as possible.

Don't consider this documentation as orders or instructions, these are
not because we are all volunteer teaming up. Consider this as a help for
us to have more fun developping AbiWord and to have a resulting
application that sucks less.

== Correct use of branching ==

We have been using branches incorrectly. The first major mistake was
that we did fix bug from the STABLE release to HEAD and then backport.
This process was really time consuming and was a real pain to follow
because we had to go thru all the changes. Sometime we just ended up
fixing things twice.

This is plain wrong. We should fix STABLE bugs into the STABLE branch
and then with merging, the later branches would get them for free. See
the next part for the correct use of CVS and how this can work
seamlessly.

We should also branch more often. For example, 2.2 is in feature freeze.
We should already have branched for release, fixed all the bugs we want
for the release in there, and eventually had new cool features in HEAD.

In short, branch at feature freeze.

This off course involve that developper have all the branch they work in
checked out on the tree, and the maintainers have all the branches
checked out and up to date. I have been doing this since the beginning,
on my slow machines (currently my fastest machine is my PowerBook G3
400Mhz....).

Then merge often to all the subsequent branches in order. We should
always merge from the older branch to the latest, by order, and not skip
any unless they are considered to be dead. The elderness of the branch
is the determined by the date of the branchpoint.

Here is a nice ACSII art to explain this:

     /--------- 2.0 /-------- 2.4
    / /
======================================================> HEAD (the trunk)
           \
            \ ------ 2.2

We merge 2.0 to 2.2, then 2.2 to 2.4, then 2.4 to HEAD. The would mean
we still maintain 2.0, that 2.2 has been released and that 2.4 is in
feature freeze about to be release. Off course we don't.

== Correct use of CVS ==

For a long time we have not been using CVS the best way. CVS as some
hugd desing drawbacks that can be worked around by some sane practice.

Branching
---------

When branching, we must set a tag for the tree we want branch first.
Basically if we want to branch MY-STABLE-BRANCH of HEAD that involve
doing the following:

cvs rtag -r HEAD MY-STABLE-BRANCH_branchoint
cvs rtag -b -r MY-STABLE-BRANCH_branchoint MY-STABLE-BRANCH

We did not do the first, so we can NOT know exactly when we branched.
This is because of CVS and the way i merge branches (per file). Tagging
the branchpoint tag the tree at the point so we can always start from
here.

Merging
-------

Then, for merging we must always have a tag indicating the the last time
we merged.

For that reason, when branching we should tag the tree by doing this:

cvs rtag -r MY-STABLE-BRANCH MY-STABLE_BRANCH_lastmerge

That way, when we want to merge to HEAD the change in MY-STABLE-BRANCH,
it is simple.

Do the following:

Create a merging tag in the source branch

$cvs rtag -r MY-STABLE-BRANCH MY-STABLE-BRANCH_merging

Then in the destination sandbox (HEAD in that case):

$ cvs -qz3 update -j MY-STABLE-BRANCH_lastmerge \
        -j MY-STABLE-BRANCH_merging

At this point, fix any conflicts ("cvs -qz3 update | grep ^C" will show
them if you missed them), build the tree and the commit when it builds
and works ok.

== Correct use of bugzilla ==

We have been using bugzilla almost correctly, but the few things I saw
that were not correct should be avoided:

Re-assigning branch specific bugs to maintainer because you only work in
HEAD is just wrong. If the bug has been assigned to you, it is likely
because it is your area.

Closing because because they are fixed in HEAD, bug not in STABLE,
because either they are to be backported or can't be fixed.
-In the first case, bug should have been fixed in STABLE, then merged
later during the merging process described above.
-In the second case, it should be attempted to fix in STABLE. If it is
not possible, then we should open a separate bug (ah, I miss the "clone"
feature) and annotate it as STABLE only.

And fix the bug for the oldest branch it has been reported against so
that we can have it in the largest number of releases.

== Implement unit testing and regression testing ==

We should implement unit testing for AbiWord. For example; all the code
in abi/src/ut/ should have a working "make test" that runs test program
for all the features (like Strings, Vector and other standard pattern
classes), including running under valgrind. I'm pretty sure we can
modify abi/src/text/ to have the similar test suite as this code is
mostly data structures and other stuff.

We should also implement regression testing to detect all the
side-effects. Main targets are all the code we can unit test and all the
code we have fixed test case like those bugs that have document
crashers, improperly loaded documents and import/export filters. Marc
Maurer and Will Lachance have implemented this for their libwpd library
(that we use) and I think we should do this for RTF, HTML, MS-Word, etc.
For wv we should make it, but this is another story.
Regression test suite should be improved for each bug fixes whenever
possible. That probably involve storing the document on the CVS, or
retrieving it from bugzilla. (I'd prefer the later, I'll think about a
design).

Off course all these test should run automatically (makefile target),
and be run under various memory checker. On UNIX that wou
We should not release anything without a successful run of both test
suite.

Please, feel free to comment.

Hub

-- 
Crazy French - http://www.figuiere.net/hub/