RADE

Source Code Manager

Setting Up SCM

How to organize people and data for starting a development project

Technical Article

Abstract

This article is intended for people getting started with CAA V5 development projects, that is, the process of developing applications based upon CAA V5 components. The reader will find here guidelines to define projects in terms of workspaces and how to manage the available development resources (data and people). Note this paper gives advice to put in place the development process but does not explain how to use CAA V5's APIs.

Some questions should have been raised before starting the project: "what are we going to develop?", "how many people are involved in this project?. If you know the answers, you are ready to read this paper and to understand the steps to follow before really starting your project.

Organizing People
Organizing Data
Starting a Software Project Using Workspaces
In Short

Organizing People

Using the CAA V5 Development Toolkit, people create personal workspaces in which they can work isolated from each other and can decide when they exchange data.

What Is a Workspace?

A workspace is the place where any program can be developed, built and tested. It belongs to one person and is dedicated to a specific task: development, maintenance, bug fix, etc. The workspace is used to gather data involved in the same software developments: they can be source files (in various languages), related documentation, program resources, test objects and so on.

From the user point of view, a workspace is represented by a hierarchy of files and directories. From the SCM point of view, these files and directories are the projection of a database object (the workspace) on the user's file system.

The Workspace Tree

Workspaces are created in a "top-down" fashion. The first workspace to create is called the root workspace and is commonly used for registering the first state (when starting a new development) and the last state (because any development will be delivered toward it) of source files.

Here is an example of a workspace hierarchy.

Fig 1: The Workspace Tree

Note that we use different colors to highlight three types of workspaces: the root workspace, intermediate workspaces and leaves of the tree. The "Root" workspace is used for receiving and storing the best level of all developments. The "Project" workspaces are used for integrating various developments and testing them before delivering to another workspace. Leaves workspaces ("Dev" and "Fix") are dedicated to individual development tasks

People working in a common development project will create their workspaces under a common project workspace.whose purpose will be to integrate their development before either delivering them or sharing them between team mates.

One Tree for One Product

Several teams can create their workspaces in a same workspace tree. However, as project workspaces will be the place of common release tasks, it is advised to gather in a common tree only teams involved in the developments of the same product line. In addition, if the number of developers is important, a single product can be split up into several components that can be managed in several workspace trees. For instance:

one tree for developing the basic software layers
one tree for developing the graphic user interface
etc

The Right Workspace for the Right Purpose

SCM manages three types of workspaces corresponding to different purposes:

The root workspace is the root of the workspace hierarchy. Its purpose is to gather all developments that have been done at any level of the workspace hierarchy. This is the first workspace to create; it is mandatory in the hierarchy. So this workspace contains the best state of files. Its children can be either project workspaces and/or development workspaces.
The project workspace: it corresponds to intermediate levels in the workspace hierarchy and is mainly used to integrate developments coming from its child project workspaces or development workspaces. The hierarchy can contain several levels of project workspaces. The development process depends on the number of levels in the hierarchy.
The development workspace: it's a leaf of the workspace tree, that means it has no child workspace. The development workspace is the real place where developments are performed, others are only there for integration. Each developer must own his/her development workspace.

There is always only one Root but the number of project workspaces is not fixed. Any development workspace can be turned into a project workspace as soon as it is specified as the parent workspace of a new workspace.

Here are some ideas about how to chose the level of project workspaces:

you use components that come from other teams to integrate them and to test the integration before the Root level
you want to perform smooth integrations of new versions of prerequisite components.

The Development Process Depends on the Workspace Hierarchy

Firstly, one must know that several trees can be managed on a site.

There are two different notions: the visible frameworks and the prerequisite frameworks.

Visible frameworks have been created in the same workspace tree and are present in a parent workspace. They can be modified in any workspace of this hierarchy. To modify a visible framework, it must be first attached using the adl_attach command. This command puts a copy of the given framework in the user's workspace and then let the user works on his/her files.

Prerequisite frameworks are not necessarily in the same workspace tree as yours. They can be used in any workspace tree but are modifiable only in the workspace trees where they are visible. This is a build concept. Please, refer to the documentation related to build tool to learn about how to manage and access prerequisite frameworks.

Fig 2: Visible and Prerequisite Frameworks

In the figure 2, Mike in his workspace Dev_Mike, develops FW3 framework. FW3 is a local framework
FW3 needs both frameworks of Dassault Systèmes (Visualization and System), installed somewhere on a file system, and FW5 which is developed by another team. Mike could never modify these three frameworks. They are prerequisite frameworks, it means that, in the code of FW3, routines of those prerequisite frameworks are called. This is really a build notion.
FW2 is a local framework of Integrate_team1. Mike in Dev_Mike sees it, he needs to modify it. FW2 is managed in the Dev_Mike's hierarchy. To modify it, Mike uses the adl_attach command to copy it into his workspace. FW2 is now a local framework.

To summarize, if one user must modify a given framework, he/she must create a workspace in the tree where this framework is managed. Conversely, if some frameworks are just needed for read access, it is not needed to copy them into a development workspace because build time and run time tools are able to access them directly (outside the SCM scope).

Different Integration Levels

The number of integration workspace has an impact on the process associated with your project. Bigger the number of integration will be, bigger the path between two development workspace will be.

Fig 3: Integration Workspaces

For instance, in the figure 3, there are two integration workspaces between "Dev" workspaces and the "Root" workspace. It means that one development delivered from one "Dev" workspace will go through two workspaces ("Project" workspaces) before being available in the "Root" workspace.

Some advantages to have several levels of project workspaces are:

To integrate progressively the new developments and the modifications
To limit the risks of bugs because tests can be run at every level
To limit the impact of incorrect modifications.

Some advantages to have few levels of project workspaces are:

To quickly share modifications
To increase the cooperative working.

At this time, the questions is "How to chose the right workspace hierarchy?". Here are two organizations corresponding to two situations:

Fig 4: Different Levels of Prerequisites

The figure 4 shows a workspace tree in which the "Root" workspace and the "Project" workspace refer to two different levels of prerequisite frameworks:

"last level of prerequisite" points to a location where the prerequisite frameworks evolves all the time
"stable prerequisite" points to a location where the prerequisite frameworks have been copied and isolated from any changes

By the way, if all development workspaces point also to the same "stable" prerequisite framework, this helps developers to work for a while without being disturbed by changes in prerequisite frameworks. When the application delivered in the "Project" workspace has reached a correct state, it can be delivered to the "Root" workspace and tested again but with a newer state of prerequisite frameworks, and so on.

Fig 5: Integrating Different Teams' Developments

The figure 5 shows a workspace tree corresponding to a software project composed of two main parts. Each part is developed independently from each other and two project workspaces have been created for testing them separately:

Each team owns a project workspace in which a local integration can be performed without managing data from the other team
Once something is available for the other team, it can be delivered to the "Root" workspace where it is integrated with the other part.

Of course this organization can be combined with the one described in figure 4.

Multiplatform Workspaces

Any workspace can be created either on Windows or Unix platforms. Multiple projections (they are called images) can be added to an existing workspace on both platforms. By the way, the organization of workspaces is not platform dependent. In addition, as data exchanges between workspaces are performed inside the SCM database (without any interaction with workspace's projections) one Windows workspace can exchange data with a Unix workspace (and conversely).

Organizing Data

How to Organize The Frameworks In Your Project?

The component oriented design offers modularity and scalability by breaking large projects into manageable pieces.

So there are two steps in your project specifications:

first to cut the project into services
and then to group these services into frameworks.

The frameworks' public interfaces list services that may be used by other frameworks. The framework is the sharing unit between frameworks, it contains an homogeneous functional set of services.

Test frameworks and documentation frameworks are associated with code frameworks. The test frameworks will contain all test scenarios, the documentation frameworks have no predefined structure and contain all documentation relative to the code frameworks. It is important for the project quality to define them at the same time as the code framework.

As the framework is the unit of working, it is sometimes interesting to split a set of services when knowing that they will be developed by two different teams.

If some services are not really components but will be used by several teams, they will be in gathered in a framework just for the sharing and the cooperative working.

How to Organize The Modules inside Frameworks?

A module implements all (or a subset) services of its container framework. It is unique among the set of frameworks.The module is the unit of build, so a module will be an executable, a shared library or an archive.

An executable is a module that can run alone.
A shared library is not executable. It can be loaded at run-time by a main module or another shared library.
An archive is a collection of object files and is not executable. It can only be referenced at link-edition to build another module.

It is more efficiently to implement the services of the framework into several modules:

to increase the concurrent engineering by dispatching the pieces among number of teams,
to share the working,
to reduce the size of the module.

There are four types of modules to address multiple needs: code modules contains the implementation of services, test modules to test code modules, education modules for the documentation and data module for the no-structured data.

If you need to share services between modules inside a framework, put them in the private interfaces of the framework.

Working With Multi-tree Workspaces

Even if several components are managed in different workspace trees, it is possible to create workspaces in which these components can be modified at the same time. SCM provides the multi-tree workspace that can be created in several trees in one command and in which all data flow commands will be executed on all trees in a single transaction (collect, promotion, synchronization, etc).

Starting a Software Project Using Workspaces

Starting From Scratch

When you begin your project, nothing is created. At least, you may have just CAA V5 frameworks.

In this part, we detail the different steps to offer a development environment to users. We suppose you know exactly how many persons are concerned by the project and the name and content of the frameworks and the modules you have to develop.

Create Workspaces

There are three types of workspaces. The responsible of a workspace is its creator. Only him/her could execute commands in this workspace.

The first workspace to create is the Root workspace. At the beginning of the project, the Root workspace is a place where all existing frameworks can be registered to SCM. Then, all along the project life cycle, the Root workspace will be the ultimate place for integrating developments.

Once the Root workspace has been created, the project workspaces can be created as children of it. Their responsibles are managers of development teams. If you decide to set more than one level of project workspaces, begin to create the level just under the Root workspace and finish with the deepest level.

The last workspaces to create are the Development workspaces.Their responsibles are developers.

Workspaces can be added or removed at any time. However the hierarchy could not be changed. It means you could not add or remove project workspaces between existing workspaces.

Create Frameworks

A framework is always created inside a workspace, create them in the Root workspace, so each workspace will see them.

The structure of the file tree associated with a framework must be respected. It is described in the file tree documentation.

If you forget frameworks or modules, they can be added later.

Any object (framework, module, file, ...) can be removed and created afterwards.SCM will warn the user to let him/her aware the object name has been already used before. It is up to him/her to check whether a name can be used or not (because the corresponding object may have been deleted or created in another workspace by someone else).

Create Modules

A module is always created inside a framework, so as for the frameworks create them in the Root workspace.

As for the frameworks, a specific file tree must be respected. It is described in the file tree documentation.

In Short

Workspaces are organized in trees whose structure reflects the composition of teams as well as the involvement of various teams in a same development project. Frameworks can be copied (if they pertain to the same workspace tree as the target workspace) or just referenced (they can be located anywhere).

History

Version: 1 [May 2000]	Document created
[Top]

Copyright © 2000, Dassault Systèmes. All rights reserved.