Difference between revisions of "CWS"

Latest revision as of 10:16, 11 July 2018

This page is archived for historical reasons only. It is no longer maintained and information may not be current.

    This article is outdated.    

CWS here is meant as the acronym for ChildWorkSpace. For a lengthier cws explanation see the introduction, the Overview, Tools (still focused on CVS though) and the CWS Policies page. 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 SVN branch, tied to a service with a database backend called EIS. The cws tooling talks to both the SVN 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.

As of the migration to Subversion the CWS tools have been reworked and there is just one cws command with different subcommands. Resyncing a CWS is different, adding modules isn't necessary anymore, and other details changed. This page has been adapted for SVN.

For more information on SVN specific CWS handling please read OOo and Subversion. If you need to work on a CWS based on legacy CVS for an OOo release 3.0.x or earlier please see an older permanent revision of this page here.

Tip: On this wiki you can use {{CWS}}, {{m}}, {{Bug}} templates to easily link to child workspaces, milestones and issues.

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 account with the appropriate commit privileges in SVN and your DSA public key file assigned for the svn+ssh protocol, and of course your DSA private key needs to be accessible to ssh on your machine, best by having added it to ssh-agent with ssh-add so you won't have to type your passphrase over and over again.

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
SVN_SERVER=svn+ssh://svn@svn.services.openoffice.org/ooo

The value for the CVS_PASSWORD attribute is taken from your ~/.cvspass file once you cvs login through the tunnel to legacy CVS. You can also use a script like this one to encrypt your password the way CVS does it. Of course Subversion will not access the CVS repository, but the CVS_ID and CVS_PASSWORD fields are also used by the cws tool for EIS access.

See .cwsrc for a complete configuration file.

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. The examples on this page here use the name link01.

For details of the cws create command please see OOo_and_Subversion#Create_a_CWS.

You need to have perl SOAP::Lite module installed for cws create 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:

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:

cws task i24253

NB. cws task: SOAP only, no SVN access.

Create a new module

This is the procedure for legacy CVS and needs to be rewritten for SVN!

(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.
• 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 external from 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 libxml2 subdirectory (in this case) in the external directory, 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.

• 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 code

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

SVN 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

Run the API tests

To ensure you didn't break API in your CWS, run the cwscheckapi command once you built the final install set to be handed to QA.

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.

For details please read OOo_and_Subversion#Rebasing_a_CWS.

See also: Merge Parts Of A CWS Into Another CWS