CWS

For a lengthier cws explanation see the introduction and Overview, Tools, Policies. This text is some really, really bare bones for the quickest, most simple cws usage.

The basic overview here is that a CWS is a CVS branch, tied to a service with a database backend called EIS. The cws* tooling talks to both the CVS server and (via SOAP) to the EIS service. 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 for people who use 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. It is also assumed that you have sourced the LinuxIntelEnv.Set.sh, winenv.set or winenv.set.sh script as appropriate, and as a result your shell is set up correctly with various environment variables pointing to the build tree.

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 and running, and the source modules you are working on has the right CVS/Root entries for that account/tunnel. (Not all source modules in the build tree need to have their CVS/Root entries pointing to the tunnel, those that you aren't going to manipulate through the cws tools can be from a tarball, or from anonymous CVS.)

You also need to have a CWS configuration file named .cwsrc in your home directory (~/.cwsrc) for any of the cws command-line tools to work. The following is an example of a typical .cwsrc file.

[CWS_CONFIG]
CWS_DB_SERVER_1=https://eis.services.openoffice.org/soap/servlet/rpcrouter
CVS_ID=foouser
CVS_PASSWORD=SDhiod0=s
CVS_SERVER_ROOT=:pserver:foouser@localhost:/cvs

The value for the CVS_PASSWORD attribute is taken from your ~/.cvspass file once you cvs login through the 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.

Filling out the details in EIS

Login with your OpenOffice.org email address to EIS. Navigate the SRC680 'new' tree - find your CWS (or better simply look it up under Child workspaces - My CWSs or to a full search with the name of your CWS Child workspaces - Search).

Then click on the underlined link at the top. Fill out the details, give a reasonable description of the CWS (not just 'bugfixes') and an estimate when you plan to have it ready for QA, add 2 more weeks to give time for QA and enter that as the final due date, dates in the format 2005-08-02.

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, if using tcsh 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. See issue handling in When you're happy further down.

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

This command must be run in the build tree in the top directory, where the modules in question are subdirectories that have been checked out through the tunnel. (Or at least, have been re-rooted to point to your tunnel in case they originally are from ooo-build tarballs.)

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.

Create a new module

(Taken from [1].)

In case you have to introduce a new module not yet known on the master workspace you have to

• first think hard if a new module is really needed. OOo now has more than 200 modules and things are getting a bit out of hand. Of course, if the new stuff doesn't really fit anywhere than a new module might be the lesser of two evils.
• create that module in cvs.
• get a cvs alias for that module so that it can be checked out by it's name.
• check in for this module to cvs HEAD in your CWS. In contrast to all added modules do not work on a cws-branch but toplevel.
• assure inter module dependencies (i.e. Hacking#prj/build.lst files) are correct. Make sure all modules needing something delivered by the new one are dependent on it. If it is not needed by any module at build time, make it a prerequisite of 'postprocess'.
• when the cws is in QA, announce the new module to Hamburg release engineering. You can do this either by writing something in the CWS description field (to RE: CWS contains new module bla) or by sending an email. This is necessary because new modules do not get tracked by CWS tooling and RE has to manually check them out before doing the integration build on the master workspace.

Additionally it is good practise to provide a short description of your new module in Source code directories table.

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 & built & tested it, you need to hand over the CWS to QA.

The issue handling of issues added to the CWS at this stage is

• Verify all issues assigned to the CWS are really fixed in your CWS build.
• If so, reassign the issue to the QA representative of the CWS.

Having done all that, login back to the CWS page in EIS and re-edit the details - marking the state to Ready for QA.

What next ?

You get to wait until the CWS is approved by your QA representative and nominated for integration, then it will be merged into HEAD and released.

The approval procedure may take some time. In the meantime the master workspace may change significantly. If changes got into the master touching the same code lines you have changed integrating your CWS will lead to merge conflicts. Resolve Merge Conflicts for CWS Integration gives some advice how to prevent problems during integration.

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.

NB. If you know what you are doing, you can resync just the files you have touched - specify the filename instead of all in -m and -c.

---

See also: Merge Parts Of A CWS Into Another CWS