CWS here is meant as the acronym for ChildWorkSpace. 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.)
cws config file (.cwsrc)
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. You can also use a script like this one to encrypt your password the way CVS does it.
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 DEV300 m16 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.
You need to have perl SOAP::Lite module installed for cwscreate to work. See CPAN install page for how to install Perl modules.
Filling out the details in EIS
Login with your OpenOffice.org email address to EIS. Navigate the DEV300 '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, as there are:
- Owner, select your account from the list if it's not already prefilled.
- QA representative, check with the project you're working on or ask on the dev@qa mailing list who the proper QA-rep for your CWS would be and select from the list. If no QA-rep is assigned, the CWS shows up under the SeekQA menu and someone might jump on it. However, it may also stay there for weeks if nobody does, so better communicate with your project. See also how to find a QA representative.
- Description, give a reasonable description of the CWS (not just 'bugfixes').
- Release, the release target, e.g. OOo2.3.
- Estimated due date "ready for QA", an estimate when you plan to have it ready for QA, in format 2002-11-23. This is to give QA an idea when the CWS will be ready.
- Estimated due date, when the CWS should be ready for integration. Note that the time span between ready-for-QA date and the final due date needs to be communicated with the QA-rep, usually it's sufficient to add 2 more weeks to give time for QA and enter that as the final due date, in format 2002-11-23. This is to give release engineering an idea when a CWS will show up for integration.
- Level of impact, One Application if working on a specific application's code, Two or more applications if working on a library used by several applications, Whole Office if touching code that is used throughout the entire office suite or affects general behavior.
Setting up the environment
Now we created a cws - we need to tell the tooling we're working with this cws; we do:
On Windows, if using tcsh the equivalent command is:
setenv CWS_WORK_STAMP link01
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:
NB. cwsaddtask: SOAP only, no CVS access.
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_DEV300_LINK01_ANCHOR tag and a cws_dev300_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 .)
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.
- please don't mix code of the core office and extensions in one module. To bring forward the modularization efforts of OpenOffice.org extensions should be treated extra to the Office code.
- create that module in cvs.
- note: if you are adding the module under external project, then creating is a bit more complicated:
- If you checkout from the CVS the external module (
cvs co external) you will get actually the
util/external, the directory
externalfrom util project's CVS. If you create a new directory, it will be committed into the util project that you do not really want.
- In order to check out the "right" external, you must checkout one of the directories of external project whose name is not identical to a directory in
util/external. For instance:
cvs co external/libxml2
- You will have to position yourselves besides the
libxml2subdirectory (in this case) in the
externaldirectory, create a new directory and commit it using
cvs add. After that, you can checkout your module and work on it as usual, still remembering that you are working on HEAD.
- If you checkout from the CVS the external module (
- get a cvs alias for that module so that it can be checked out by it's name. See the procedure in http://external.openoffice.org/ and additionally example Issue 76452 (assign it to mh). this is coupled with the legal review of the new external code, so that the new alias will be available once the review has been done.
- 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 practice to provide a short description of your new module in Source code directories table.
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.
- Announce new features and enhancements (not mere bug fixes) using the feature announcement form within EIS.
Having done all that, login back to the CWS page in EIS and re-edit the details - marking the state to Ready for QA.
Check your changes. If you did some binary incompatible change mark the corresponding module incompatible.
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.
- step1 : prepare the place
mkdir tmp cd tmp export CWS_WORK_STAMP=the_name_of_the_cws
- step2 : the resync itself
Case 1 : for cws created against DEV300_m0 or later
cwsresync -m m5 all ... resolve possible conflicts ... cwsresync -c all cwsresync -f -l m5
Case 2 : ATTENTION: If your cws still is based on SRC680, use the following
Please note that "cwsanalyse all" may not work in this case
export WORK_STAMP=SRC680 # means the cws was created using SRC680 Master work space, does not exist in DEV300 database # and the build environment did probably define DEV300 as $WORK_STAMP instead cwsresync -m DEV300:m5 all ... resolve possible conflicts ... cwsresync -c all cwsresync [options] -f -l DEV300:m5
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 protocols 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 during the third step.
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