There are a number of reasons for the existence of ooo-build:
A simple cvs tag of the whole of the OO.o tree can take several hours to complete; thus if you want to have a very extensive patch set against OO.o you cannot work at a sensible speed. All cvs operations, branching, merging, re-synching even simple updating, take a very considerable time. Working from a separate base tar.gz and a flexible patching system allows the maintenance of a branch very much more easily.
Why do we have to have a branch, and a large patch set at all ? why can't we just work directly from OO.o CVS.
There are several answers here: primarily that CVS commits are extremely restricted, the approval process from IssueZilla submit to eventual CWS commit, to CWS merge takes a matter of weeks; this is no way to create excitement, and provide fast problem fixes. Furthermore, there are constraints to merging to a stable branch that disallow many changes. Large changes cannot happen eg. (a base vtable change, new icons) since Sun have to ship binary bug fix updates - which are required to be reasonably small (ie. not all of OO.o again).
Furthermore, Sun will only accept patches after receipt of a posted / FAXed, signed JCA. While we feel the JCA is a vital to OO.o and mandate it's use for ooo-build commits, we are happy to prune this postal / processing / CVS account bug ticket creation / CVS account bug ticket assignment to collab.net / CVS account creation / commit latency. With assurance of an in-flight JCA - we can create a CVS account quickly and get you working with a handful of hours.
Sun has a need for a highly stable / buildable branch from which they can make releases. There are two approaches to get a stable/buildable branch:
While B. results in frequent, temporary breakage, this is soon fixed, and life is fast, smooth and happy. The existing situation: A. leads to communal frustration / strangulation - however it does provide a stable branch at most times.
Of course - hopefully at some time in the future problem 1.1 may get fixed - at which point keeping a branch in OO.o cvs that allowed sensible communal development, while allowing merge-backs to stable would be feasible.
The core OO.o build process is not easy to use, and the packaging process on Unix is anachronistic, and inflicts incredible pain on sysadmins and users. Thus, this has to be worked around externally to OO.o. This is a substantial amount of work - unfortunately, it seems the re-creation of a Unix build is also a pending internal task - hopefully this will not result in an even bigger mess of alternative packaging schemes.
We have introduced a way to select a subset of patches to apply to a particular build. For example, Ximian uses a set of patches to use CUPS as the printing system, which Debian, as a more general distribution cannot do, but both packages use the fontconfig support.
It also gives the patches a chance to be tested by a wider user community while they await integration into the main version.
There have been for many years, very many patches against OO.o to do all manner of useful things. Many of these have been submitted under the JCA. The pace of adoption of these changes is really depressingly slow; and the level of engagement with external contributors poor. In some cases whole chunks of functionality have been re-written internally without reference to, acknowledgement of, or discussion with the original author - this phenomenon continues apace.
Without communication it's impossible to co-ordinate what is being done. It's also impossible to have any confidence that your patch will be useful / nicely designed. To try and overcome this, and to encourage each other - we hang out on channel #OpenOffice.org on irc.freenode.net, you'll soon get to know the team. See also here to see who is whom.
We also have a mailing list - which you can subscribe to here, where we discuss various issues related to ooo-build.
So; since the source tar.gz is a snapshot taken from a random user's account; you need to switch this to using the anoncvs root; to do this cd build/OOO_1_1_0 (eg.) and run bin/re-root . - this will switch the CVS/Root directories to use the anon-cvs server. To verify that this has worked, do: cat moz/CVS/Root, and check it contains:
':pserver:anoncvs@anoncvs.services.openoffice.org:/cvs'.
Since we are interested in diffs from the toplevel - which has no CVS directory; we also need to do: export CVSROOT=`cat moz/CVS/Root` NB. '`' is a back-tick.
It is of course crucial that you or your company have signed and posted the JCA; see here.
NB. the openoffice sources i.e the sources in build/OOO_1_1_0 are in openoffice.org anon-cvs server, whereas the toplevel files i.e ooo-build/*.* are in gnome cvs server. So for openoffice sources you have to set CVSROOT(as above) for performing diffs from the toplevel.
Having done this we can make a patch; taking the sample toolbar change from here we would do this:
cvs -z3 diff -up vcl/source/window/toolbox.cxx | tee ../../patches/OOO_1_1/gui-toolbox-hack.diff
NB. to append a patch to an existing diff use tee -a
NB. to avoid having to type -z3 & -up grab this and put it in ~.
If you're going to create or edit many patches, you should try quilt.
Also interesting if you edit patches:
patchutils
and Miles Bader's way of
handling rejects with (x)emacs diff-mode
Before committing the patch, we need to submit it to IssueZilla (IZ) - this is about the most painful bit: re-login (again), hit File an Issue, commit the issue, and attach the patch - remember the IZ number.
Having created the patch, you then need to edit the relevant apply set; eg. patches/OOO_1_1_0/apply and add the patch to a relevant section, along with a comment line that describes it - and references the IZ number. eg. # this adds a nasty hack to the toolbar - #32179 gui-toolbox-hack.diff
ooo-build/bin/re-root ooo-build ':ext:UserName@cvs.gnome.org:/cvs/gnome'
First ensure you have a ChangeLog entry in ooo-build/ChangeLog, this should look like:
2003-10-23 FirstName LastName <EMail@MyCompany.com> * patches/OOO_1_1/gui-toolbox-hack.diff, * patches/OOO_1_1_0/apply: add a nasty hack for toolbars.
Now, from the toplevel directory run cvs commit, use your ChangeLog text for the CVS commit message.
When there's a particularly good reason for a release, such as a distro needs a stable base / we want to do something potentially disruptive, one of the core ooo-build hackers will follow something like this process:
cvs update - get the latest everything
Read back through the ChangeLog and update the NEWS file for the release, summarizing and attributing the changes.
edit configure.in, bump the version in the AM_INIT_AUTOMAKE line, incrementing the minor version eg. AM_INIT_AUTOMAKE(ooo-build, X.Y.Z)
./autogen.sh - this re-builds configure with the version in place.
make dist - this builds the archive containing everything.
Add a line to any handy ChangeLogs saying:
2019-13-33 Ned Squeers <ned@sqeers.com> * Version X.Y.Z
so we can easily see where this happened in the flow.
cvs commit - so what's there is what's there. If there was a collision you get to loop to the first stage here, but don't re-increment the number.
cvs -z3 tag OOO_BUILD_X_Y_Z - this leaves a static tag so we can reproduce the build at any time and easily diff between releases.
scp ooo-build-X.Y.Z.tar.gz ooo@ooo.ximian.com:/var/www/packages/OOO_1_1_0 of course, substitute the branch/ver for OOO_1_1_0.
It's then customary to announce the release, see the template in doc/announce.txt - update all the ***s to the right versions, insert the contents of NEWS, fire and forget.
This section is mostly of interest to people helping administer the ooo-build package over time, and to avoid the patch set getting too tangled and messy.
Taking the example of an upgrade from OO.o 1.1.0 to 1.1.1, there will be several directories, that should end up containing this:
patches/ OOO_1_1/ - only patches against the latest OOO_1_1_X version OOO_1_1_0/ - 'apply' file, and old/stale/different patches OOO_1_1_1/ - only an 'apply' file.So - clearly in order to arrive at this scenario, we have to cvs add the new OOO_1_1_1 directory and it's apply file (based on the OOO_1_1_0 apply), and for each patch there are three scenarios:
mv OOO_1_1/foo.diff OOO_1_1_0 cvs remove OOO_1_1/foo.diff cvs add OOO_1_1_0/foo.diff
cp OOO_1_1/foo.diff OOO_1_1_0 cvs add OOO_1_1_0/foo.diffand then re-generate the diff for 1.1.1 into OOO_1_1/
Final caveat: this works nicely for 2 version, but what about 3 or more, should we move a conflicting patch for 1.1.2 into both 1.1.1 and 1.1.0 ?. For complex scenarios we can update the PATCHPATH in various 'apply' files to avoid excessive patch duplication, and prune ancient versions over time.
Of course this has a number of obvious down-sides for you as a contributor:
Working outside CVS makes up-streaming harder, and commits somewhat more painful.
You get no immediate 'official' recognition; no-matter how large your contribution is to OO.o. You don't exist in the eyes of the artificial OO.o community as ooo-build is not an 'official' project; however - we value you more.
Obviously the existing situation is highly sub-optimal, here are some possible improvements beyond our control that could be made:
accelerating CVS performance - this is a hard task, possible subversion may solve this in due course. A more feasible alternative would to devote resources to committing to merging CWS' targeting stable to a parallel playground branch in OO.o CVS as well [ thus avoiding painful community merging ].
accelerating OO.o CVS account creation, binning ACLs and hugely increasing access (& trust); thus we can get more people involved more quickly without demoralisation.
aggressive interest in working with external people, and merging their patches; this involves at a minimum:
recognising the needs of Unix packagers to have substantial wrappers / work around OO.o, and allowing them to integrate all of it, leaving no need for separate branches.