# The even quicker hackers' CWS howto

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 knocked up by Kendy it is here: cws-commit-patch, and works well.

### 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 script and have you shell setup right.

It is also assumed that you have an up-stream OO.o cvs account, 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`

### 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'. 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
    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.