Guidelines for Keeping Projects Autonomous

The time-honored programming tenets of high cohesion and low coupling apply to StarTeam projects as well. The more independent your StarTeam projects are, the easier they are to secure, administer, and even separate from the original StarTeam configuration if necessary. Keeping projects autonomous means keeping cross-project links and shares to a minimum, avoiding them completely if possible.

Below are some guidelines for deciding what should be in the same project:

A project should be used to manage the life-cycle artifacts of a cohesive application set or application component set. Examples are a commercial software product or a foundation library package. Multiple application or component sets can be managed in a single project if they are interrelated and generally enhanced and released together.
A project should include all of the artifacts required to manage the life-cycle of the supported applications or components. This includes early life-cycle artifacts such as requirements documents, modeling diagrams, and design documents, as well as construction phase artifacts such as source files, images, and resource files; and later-phase artifacts such as test scripts and applications.
A project should include all artifacts authored in life-cycle phases as well as non-authored artifacts required to perform authoring. This includes, for example, all files authored by the IDEs such as workspace/project files, source code, and resource files. It also includes “input files” such as .h, .lib, .jar, or .dll files that are authored or generated elsewhere but required by the project’s IDEs or build processes. Input files may originate from third parties or from other projects in the same or other StarTeam configurations. (Transferring artifacts from one project to another is discussed further later).
Files directly generated from authored files such as .obj, .class, and .lib files generally do not need to be checked into the project. However, it is common practice to check in “final” binaries such as .jar, .war, and .exe files that are delivered to other projects, engineering test, QA, or other deployment phases. The need to place generated files under version control is highly dependent on your own development, testing, and release methodologies.
A project should have a long-term view of the products or components it supports. That is, it should house all artifacts generated over multiple iterations through the lifecycle. This means that the project supports multiple versions of its applications or components, representing the complete history of those modules.
StarTeam works best when “work” artifacts (change requests, tasks, topics, and requirements) related to a project’s files are stored in the same project. This allows, for example, a change request to be entered, tracked, and linked to the files in the same project to which the change request is related. This approach requires some special considerations for activities such as “change request triaging” and cross-project reporting. These issues are discussed later.

Some customers have attempted to use projects to separate development phases (for example, design and development) or development artifact types (like files and change requests). The artifacts are then interrelated by sometimes heavy use of links or shares. However, experience has found that copious use of shares – especially cross-project shares – results in difficulties in version control, reporting, security, and even performance. We suggest that artifacts related to the same applications and components, even though of different types/life-cycle relevance, should be managed in the same project.

Scenario 1: A Simple Client/Server Application

A commercial software application consists of a server written in C++ and a single client, also written in C++. Furthermore, the client and server modules share a fair amount of source code and IDE projects that generate common DLLs. The client and server modules are generally enhanced and released together.

In this scenario, a single StarTeam project should be used to manage the combined files of both the client and server modules. The sharing of source code and shared release schedules suggest that the modules are cohesive parts of a single application. Requirements, design documents, change requests, and other artifacts required for all life-cycle phases of the client and server modules should be managed in the same project.

Scenario 2: An Independent Client Module

A new Java client application is developed that uses the same server described in Example 1. Building and compiling the Java client requires some of the header files and one of the DLLs used by the server to produce a JNI wrapper, but no other source files. Furthermore, the Java application accesses other third-party servers and is generally enhanced and released on independent schedules from those used by the client/server modules.

In this scenario, it is reasonable to use a separate StarTeam project to manage the Java client’s artifacts. The latest header files and generated DLL needed by the Java client are checked into a “external components” folder by the build process used in the client/server project. All change requests, tasks, and other life-cycle objects related to the Java client are managed in the same project.

Scenario 3: A Complex Financial Application Suite

A complex application suite consists of a set of foundation components and nearly 100 separate applications, divided into five functional areas: accounting, insurance, forecasting, etc. The applications are developed by different teams and all use the foundation components, which are jointly maintained by the development teams. Applications within a functional area are highly interrelated, but applications between functional areas are fairly independent. The foundation component library is enhanced and released on its own schedule, but the entire application suite is released as a commercial product in coordinated releases.

Although the entire application suite is interrelated, multiple projects should be used due to the overall application suite size. The foundation components are managed in one project, and each of the five functional areas utilize a separate project to manage the corresponding applications (six projects total). The foundation project is enhanced, built, and then “deployed” to each of the functional area projects by checking in generated jar files. Each development team generally opens only one project to perform their normal work. However, a special build script (using the StarTeam SDK) is used to extract files from multiple projects and generate “whole suite” builds. The build script also automates the management of common view labels and promotion states across projects.