StarTeam Containers and Artifacts
StarTeam Server configurations, projects, and views are containers that allow you to organize artifacts based on application, module, business unit, or other criteria. These three basic containers are illustrated in the diagram below:
Server Configurations
A server configuration is also referred to as a repository or as an instance. All files, change requests, and other artifacts that can be interrelated and managed as a whole reside in the same configuration.
Note: Throughout the documentation, the terms server configuration and server are also used interchangeably. This is because each server configuration is often deployed on its own server machine, managed by its own StarTeam Server process. However, be aware that StarTeam allows multiple server configurations and server processes on a single machine, so the server configuration-to-machine relationship does not have to be one-to-one.
Projects
Within a server configuration, artifacts are organized into projects, which group and manage related items hierarchically in a set of folders. Creating a project allows you to put files under version control, set requirements, track change requests, manage tasks, audit user actions, and discuss the project. Each project has at least one view, called the initial or root view. For example, a project for a software product might include files on the product’s functional specifications, marketing requirements, source code, and test suites, all stored in separate folders in the initial view. As the product progresses from one release to another, additional views of these folders can be created. One view could represent the 1.0 version of the product, while a second view represents the 2.0 version, and so on.
Before a server configuration can be used, at least one project must be created. A server configuration can hold multiple projects, each oriented to the lifecycle needs of a specific team, application, or component. The configuration in the diagram above has two projects: BedRock, perhaps for foundation components, and AppSuite, which could be used for applications belonging to a common suite.
Views
Each project consists of one or more views. Think of a view as a subproject. It is a subset of the project’s contents that support a specific activity. Every project automatically receives a main view through which folders, files, and other objects can be organized. Additional child views can be created to represent subsets of the main project information, historic snapshots of project information, or work areas for new development work. StarTeam provides a wide range of options for view creation to support a wide range of development scenarios.
Workspaces
In addition to the three basic containers, StarTeam supports a client-side container called a workspace. A workspace is a folder hierarchy located on your computer or in your personal directory on a shared file server. However, the project does not have to exactly match your working folder and its child folders. For example, you may omit child folders in the working folder from a project or copy only specific child folders in an existing project to the working folder. When you add or check in files, the application copies the files from the working folder into the repository. When you check files out, the application copies the files from the repository into the working folder.
In addition to providing a well-defined area for check-in/check-out operations, a workspace allows StarTeam to compute the status of each file: which ones have been modified since they were checked-out, which ones are out-of-date, and so forth.
Artifacts
A typical software development lifecycle requires the development, evolution, and management of things other than source files such as requirements, models, graphics, change requests, schedules, tests, and so on.
The term artifact refers to the generalization of objects that can be versioned, branched, merged, etc. StarTeam supports non-file artifact types directly, providing type-specific behavior for storage, versioning, merging and so forth. All artifacts are versioned, and some are branchable.
The built-in artifact types supported by StarTeam are summarized below:
Folder | Every view has one
|
File | StarTeam allows you to store any kind of file: text or binary, authored or generated, small or very large. A few more features are provided for text files such as
|
Change Request | A
|
Task |
StarTeam
|
Topic | A
|
Requirement | If you do not have a formal requirements management (RM) tool, StarTeam requirements provide a convenient, lightweight artifact with which requirements can be captured. Requirements can be arranged hierarchically to represent decomposition, and they can be linked to other artifacts. Since requirements are independently-versioned artifacts, they are more accessible than requirements buried in documents, which are versioned at the whole-document level. If you use a requirements management system such as Caliber, those “formal” requirements can be imported as StarTeam requirements and organized together with other lifecycle artifacts. We provide integration tools to import, synchronize, and even link artifacts between StarTeam and Caliber. Requirements do not branch. |
Audit | An
|
These artifacts are all bundled with
StarTeam, however you are not obligated to use them all. The code for each artifact type is encapsulated in a dynamically-loaded plug-in module called a
Note:
You always get folders, so there is no
Artifacts versus Items
The difference between artifacts and items is that you can only access and update artifacts through items. Since StarTeam blends item and artifact properties into a single object (both graphically and in the SDK), you may think of them as a single concept.
Although either term works equally well in most cases, we usually use item when we mean to include folder/view context that items add to artifacts. When the context is not important to the discussion, we use the term artifact.
The following table summarizes the most important things to know about items and artifacts :
Artifacts can only be accessed through items | With StarTeam, you can only fetch or update an artifact by directing your request to a specific item. There are no commands to directly access an artifact independent of an item. This means that all artifact access is influenced by the context of the associated item such as its parent folder and the view in which it lives. |
Items form folder trees |
|
Items facilitate sharing | Items allow an artifact to appear in multiple folders, views, and projects. To make an artifact, including its entire history, appear in a new location, we only have to create a new item, which is pretty cheap. Sharing is analogous to “hard links” used in UNIX file systems. |
Items influence version behavior | An item has properties that control what artifact revision is referenced and how updates through the item are handled. Items store an OID that determines what artifact branch is referenced. An item also stores a
false . Note that
branch-on-change cannot be true for items that point to artifacts that can’t branch (such as topics). Also, an item with
branch-on-change equal to false and a pinned configuration timestamp is read-only because we can’t update a historic revision and we can’t start a new branch!
|
Items create promotion trees | This is an advanced concept, so we’ll just touch on it briefly here. Items that are shared to a new location “remember” the item from which they were shared. This “share parent” relationship is different than the “containment parent” relationship that forms item paths. It facilitates a concept called automatic promotion. |
Sharing and Cheap Copies
Over time, you will have a lot of artifacts, especially files, and some files will have a lot of branches. Consider the effect of containers: if you have a lot of teams, software components, and releases, you will need a lot of independent projects, subprojects, or other containers to support parallel development and separate maintenance. Often the same files will be needed in each of these containers. How do you get the files you need to each of these containers? Forcing every file to branch in order to get a unique branch in every possible container could be a lot of branching, which is expensive.
StarTeam systems addresses this problem with a technique known as cheap copies. This involves creating references to files in a new container. Similar to UNIX links, this happens without actually copying the files themselves (that is, their content or their history). Unlike UNIX links, however, the first time a file is modified via a new reference, it is branched. For this reason, cheap copies are also referred to as “copy on write” sharing. Cheap copies support efficient branching with large projects.
In StarTeam, the folder hierarchy and the contents of each folder are specific to each view. Artifacts can belong to (or more properly be exposed through) any number of views and projects. Items are objects that select specific artifacts, connect them to a specific view, and organize them into a hierarchy. The diagram below shows how this works.
Every view has a root item, which always points to a folder artifact. In this example, the root folder name is foo. We can make any artifact in the repository belong to this folder by creating an item that points to the artifact we want and the root item as the parent. In this example, the files a.txt, b.java, and c.jar and the folder bar are all child elements of the root folderfoo. As you can see, the concept of path name is formed by concatenating the names referenced by the item structure. In this view, there is a file whose path name is /foo/bar/d.doc because we can get to this artifact via the item path: folder foo to folder bar to file d.doc. If we want to change the folder in which d.doc appears, we change the parent of its associated item, the artifact itself is not modified. Notice that two items reference the file c.jar. This means that this file is contained in two different folders. We say that the file is shared in two places. This is analogous to UNIX links that reference the same file, causing it to appear in multiple directories. Sharing allows any artifact to be shared in multiple places. Since artifacts are “heavy” (they contain all the properties) and items are “light”, this is how “cheap copies” are made: we just create items pointing to existing artifacts.