CWS Policies

These Child Workspace (CWS) policies define the rules for quality driven software development. These rules are based on current knowledge. They will be updated with further experience and will be adapted accordingly.

Child Workspace Creation

A CWS can be created unconditionally. Use the CWS to solve existing issues, when you fix something in a CWS make sure that a corresponding issue exists and is added to the CWS.

The Scope: How to group tasks

A CWS is associated with at least one issue. An issue should only be assigned to a single CWS. Multiple simple issue – e.g. minor fixes – shall be associated with a single CWS. A more complex issue – e.g. a new feature – has to be associated with its own CWS. There are several categorizations of issues possible:

1. High-impact features: Features that change user interface (UI) or workflow significantly. This includes minor changes of frequently used features, e.g. main menu items, common shortcuts, and default tool bars. Typically needs support from the User Experience (UX) team. An implementation team (I-Team) will be formed with members from development, UX and Quality Assurance (QA). This team develops a functional software specification, a test case specification and adapt the test scripts for automated testing (VCL TestTool) for this new feature.
2. Lower-impact features: features which have limited impact on UI or workflow. This may include changes of less frequently used features, existing User Interface guidelines or other guidelines can be used.
3. Bug fixes category A: code changes modifying the layout of the UI , with changes in workflow or other significant code changes.
4. Bug fixes category B: code changes which can be verified best by developers.
5. Infrastructure issues: task, which are not directly related to the Office or another product.
6. Documentation: Changes in online help, README
7. Translation: localization issues

Issues should be grouped in a way, that a meaningful categorization of the CWS as above described can be done. Tasks should be registered in a CWS with agreement of all members of the CWS.

The Team: How to group people

For all child workspaces at least the “four eyes principle” should be applied.

• High-impact features: Developers, UX, QA and Documentation.
• Lower impact features: Developers, QA.
• Bug fixes cat A Fixes: Developers, QA
• Bug Fixes cat B: Developers, QA role taken by Development
• Infrastructure issues: Developers, QA role taken by Development
• Documentation: Documentation, QA role can be taken by Documentation
• Translation: Translation, QA role can be taken by the L10N teams or Documentation

regardless of this categorization any member of any group can volunteer to participate and request another categorization.

Build Configurations

A Master Workspace (MWS) is built and tested in it's “product” and “non-product” builds on the "standard" platforms – currently Linux(x86), Solaris(Sparc), Solaris(x86), and Windows (32bit). Unless a CWS has a multi-language scope, a CWS delivers single language builds. The default language shall be “01” (en_US). A CWS must be built on at least two platforms in the ”product” version (Windows and one UNIX platform) unless platform specific code of another OS is changed, in this case make sure that this platform is also tested.

Work on a Child Workspace

• The CWS “owner” should coordinate the code changes in CWS.
• Issues can be added or removed to represent the status in EIS. See above on how to group tasks.
• There will be no minor versions in a CWS.

Synchronization with Master Workspace

Synchronizations are useful, or may even be required, when a CWS already exists for some time to follow up with the changes that have been integrated into the master workspace during that time.

Using the Environment Information System (EIS)

Access to the EIS is given by the URL http://eis.services.openoffice.org/EIS2/servlet/Logon Provide the necessary information about your CWS in the EIS database: Owner, QA representative, tasks, etc. Using 'xxxx@openoffice.org' (the @openoffice.org is mandatory) as the user, and your openoffice.org website password, as password. Replace xxxx by your userid.

Making the CWS "Ready for QA", "Approved by QA" and "Nominated" for Integration

A CWS must meet certain required criteria in order to be nominated. A CWS should meet certain recommended criteria as far as possible, for example criteria which may depend on further experience. A CWS is nominated for integration in three steps.

1. The CWS “owner” sets the state of the CWS to "Ready for QA", if the CWS fulfills all criteria described below.
2. The QA representative is responsible for organizing the QA effort and either set the CWS back to "New", if problems or regressions against the corresponding MWS build are found, or set the CWS to the state "Approved by QA" or “Nominated” if all tests passed.
3. There is also the role of a “Gatekeeper” , who watches out for process violations. He has the authority to stop a CWS even after QA approval, if the QA was not done according to the rules. The release manager (one or more members of the release status meeting) will do the final nominations on release code lines.

Making the CWS "Ready for QA"

As a major rule: Never introduce new known bugs into the master.

Check if all of the following points are fulfilled before setting the CWS to "Ready for QA":

Mandatory points:

• The CWS has to be consistent.

If, for example, a feature was added in the CWS that needs a new (or changed) description in the help, than the CWS has to include the module 'helpcontent2' and the changed help texts have to be there. It is also needed to add the qa/qatesttool module, when in the CWS new UI or changes in handling/work flow of features are added. The test script for automated testing with VCL TestTool has to adapt in the CWS too.

• Do a smoketest for each platform. (cd smoketestoo_native && build )
• Describe features, documentation and / or user interface changes in EIS under Changes-Mails->New external feature.
• Document any interface changes in EIS under Changes-Mails->New external API.
• Flag any modules with binary incompatible changes in EIS.
• Make sure that all implemented features and bugs fixes are registered at the CWS and that they are really implemented and fixed. If a task is fixed in other cws, it has to be removed from this CWS.
• Verify that all issues which are assigned to the CWS are fixed/resolved and reassigned for verifying.
• (Only if applicable) Make a specification available, see the Specification Guide at http://specs.openoffice.org.

Desirable points:

• Synchronize to the latest milestone.
• Don't introduce new compiler/linker/etc. warnings. Write OpenOffice.org coding guidelines compliant code.
• Get new and changed interfaces reviewed. This refers especially to IDL interfaces, but also to C++/Java etc. classes which will be used from more than one or two clients.

Nice to have points:

• “lint, or valgrind”- like code checks.
• Upload the install sets to: ftp.stardiv.de. Ask at dev@openoffice.org for details.

Some of above criteria may need some “flair”.

Setting a CWS to "Approved by QA"

The whole approval process can be found at Approve a CWS. A check list for incoming CWS and a action list for verifying issues in a CWS are included.

A QA representative for your CWS can be found at Find a QA representative. Main points from the approval process are the following :

Mandatory points:

• Complete the tests successfully.
• The QA representative decides when enough tests are completed.
• (Should for bug fixes) Make a test specification/test case available, including a check whether the test specification/test case might need an update.
• Ask developers to approve the test specification/test case.

Desirable points:

• Let any raised assertion make the test fail.

Integration

Integration into master workspace is done by Release Engineering.

CWS can be rejected by RE in this phase (e.g. when it doesn't follow license rules of our project, headers contain deprecated SISSL license etc.). Such CWS is set back to New state.

Integration failure / later QA failure: If this is not resolvable, the CWS is rejected and the MWS returns to the last milestone before. A CWS cannot be reused. Once it is integrated back into its master, the CWS is dead.

Integrated CWS

Information about the integrated or deleted CWS will be kept in the EIS database.

Appendix

Known pitfalls and other problems

Separation among "Developer" and "QA" does not make sense in every case. Code changes, which will not change the programs behaviour (class redesign, removal of warnings, porting stuff). These kind of issues should be reviewed and set to verified by a peer. In these cases the I-Team should think of requesting a full automated test. Several reintegrations are done at one time. In the ideal world there would be only one reintegration of a child workspace back into the master at a time and every child workspace would be resynced before reintegration. practice has shown, that:

• most of the child workspaces get nominated close to deadlines, so more than one child workspace get reintegrated at a time.
• QA does not have unlimited resources, this has the consequence that the time frame for nomination can last some days. Usually a CWS get resynced before QA approval, so that at nomination time several CWS got integrated into the master and the chance of conflicting merges will rise.
• resync and rebuild of a cws can last some time (depending on the amount of modules and the degree of incompatibility of the integrated CWS since the last resync).
• working with child workspaces gives the illusion that you're living on an island: you don't interfere with anybodies work outside your I-Team. But this will move the work into the reintegration phase: you will have conflicts !

Therefore it might be useful to:

• use cwsanalyse to determine potential conflicts. Resolve them in advance without rebuilding your complete CWS.
• If you plan bigger changes in the code, please communicate this on the dev list for better scheduling of these kind of child workspaces.

In cases the master workspace is broken, there are two possibilities:

• the easy case: The problem is discovered quickly, a P1 issue has been filed and the fix is also already available. Coordinate with Hamburg release engineering on how to get this fixed on the master workspace.

• the more difficult case: defects are discovered late in the process, the problem has been handed down to derived child workspaces, it does not affect all participant (P2/P3 issue). If the fix for this case has been applied at one of the living child workspaces, it can last some weeks until it get integrated into the master. If you're dependent on that fix you have to apply it yourself or have to workaround this in the meantime. This will likely cause merge conflicts again at reintegration time and cause some pain to people concerned.

Take the idea of the I-Team seriously: Communicate with your QA-Rep and QA folks early and often: What is expected to be in the child workspace, where to get the installation sets to test, which build configuration to test, etc.

Reasonable exceptions from the above listed rules are allowed: they should be requested on releases@openoffice.org (of course with well thought out reasons ;) ).