CWS

For a lengthier cws explanation see here. This text is some really, really bare bones for the quickest, most simple cws usage; all fields that you'll need to change are italic for ease.

The basic overview here is that a CWS is a CVS branch, tied to a database called EIS. The cws* tooling talks to both the CVS server and (via SOAP) to the database. It makes maintaining branches more efficient, standardises their use & integrates with QA nicely.

All code that goes into OO.o has to go through a CWS. A CWS is a fairly heavy-weight beast - thus it's well worth aggregating several commits / bug-fixes into one.

NB. Since this 'howto' was written an even quicker way of committing patches to a cws has been created: ooo-build/bin/cws-commit-patch.

Basic setup / Assumptions

It is assumed that you have fixed some bug / created some feature, and you have a live build tree in /opt/OpenOffice/src680-m76. It is also assumed that you have sourced the LinuxIntelEnv.Set.sh or 'winenv.set' script as appropriate, and as a result your shell is set up correctly.

It is also assumed that you have an up-stream OOo CVS account with the appropriate commit privileges, and that you have your tunnel setup correctly, and the source has the right CVS/Root entries for that account/tunnel.

Creating the cws

You have to think of an imaginative name for your cws; if it's just some general bug fixing thing, people tend to use account-name<index> otherwise some more descriptive name

cwscreate -f SRC680 m76 link01

NB. the -f stops cwscreate doing a slow, monstor fresh check-out (you don't want that).

NB. cwscreate in this mode: SOAP only, no CVS access.

Setting up the environment

Now we created a cws - we need to tell the tooling we're working with this cws; we do:

export CWS_WORK_STAMP=link01

On windows, you will be using tcsh so the equivalent command is:

setenv CWS_WORK_STAMP link01

Adding tasks

The CWS (in order to ever get merged) has to have a number of issues associated with it, describing the bugs fixed in this CWS. The developer should mark these as 'Fixed' as he commits/tests & QA should mark these bugs 'Verified'.

question: What is the correct handling here? I thought that the developer had to find a QA person, then re-assign the bugs to that QA person, which would reset the status of the bug to 'New' - you cannot reassign a bug which has a resolution of 'Fixed' Mtg

It's also important to get the Milestone correct in the bug. To associate the task with the cws do:

cwsaddtask i24253

NB. cwsaddtask: SOAP only, no CVS access.

Adding modules

We now need to add some top-level modules to the CWS - the ones that we have changed. This tool essentially just tags cvs twice with a static: CWS_SRC680_LINK01_ANCHOR tag and a cws_src680_link01 branch tag to commit to. It then updates the module to that branch.

cwsadd -a -f solenv

NB. here -f allows you to keep your changes, while doing the tagging on the underlying versions they are based on - incorporating them into the new cws automatically.

NB. cwsadd: SOAP and CVS access.

Committing code

Committing requires nothing particular new; the database doesn't track commits. Just commit them to the branched modules you cwsadded.

CVS should add some helpful fields for you & some helpful blurb about what to write here - often it doesn't. The stock format is:

Issue number: #i24253#
Submitted by: mmeeks
Reviewed by: mmeeks
This patch fixes a silly bug in linkoo

When you're happy

Finally - when you've committed everything & tested it, and/or if you're strange & like to have a long-term cws open you need to setup your cws details in EIS.

Login with your SourceCast account details (log out first). Navigate the SRC680 'new' tree - find your cws, and click on the underlined link at the top. Fill out all the details, dates in the format 2005-08-02.

Having done all that, go-back, and re-edit the details - marking the state to 'Ready for QA' [ you did mark all your bugs 'FIXED' first ? - don't run foul of the thought police ].

What next ?

You get to wait until the CWS is nominated by Sun QA up-stream, then it will (eventually) be merged into HEAD and released.

Updating to a newer milestone

The long-term CWSes need a resync to a newer milestone from time to time.

mkdir tmp
cd tmp
export CWS_WORK_STAMP=the_name_of_the_cws
cwsresync -f -m m79 all
... resolve possible conflicts ...
cwsresync -f -c all
cwsresync -f -l m79

You must start in an empty directory with a correctly set CWS_WORK_STAMP environment variable. First of all, -m merges files from the CWS (according to CWS_WORK_STAMP) with the specified milestone and protocolls all conflicts. -c then commits the merges to the CVS. NB.: Do it always with cwsresync -c, never by hand! Finally, -l updates the workspace and the milestone info of the CWS in the database

NB.: Don't forget to create a new & empty directory for this. Really.

NB. -f: Speeds the things up by avoiding unnecessary updates.