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:

In this topic:

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.

Back to top

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.

Back to top

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 root folder, which typically has a tree of subfolders beneath it. Folders are patterned from the file system concept of directories. In many cases, you will want to create StarTeam folders that mirror specific directory structures. However, StarTeam folders can hold any kind of artifact, not just files. This concept may seem strange at first, but when you discover that you can organize change requests, tasks, and other non-file artifacts the same way you organize files, you will find this feature very powerful. Folders can branch, allowing the same folder to have different properties in each branch.
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 keyword expansion and EOL conversion, but all file types otherwise are treated identically. StarTeam allows single file revisions larger than 4GB. Files are branchable, allowing parallel version streams and merging.
Change Request	A change request (CR) is a general artifact that can represent a defect, enhancement request, or another reason for a software change. Because CRs are often the center of change management, the CR type is frequently extended with custom fields, custom GUI forms, and workflow rules. CRs can branch, allowing parallel modifications to the same CR for separate activities such as fixing the same defect in multiple releases. Using integration tools, you can import CRs from and keep them synchronized with other defect management systems.
Task	StarTeam tasks are modeled after project management tasks: they can be arranged hierarchically to represent task decomposition, they can be connected with predecessor/successor relationships, and they can be updated with progress units known as work records. You can import tasks from a project management system such as Microsoft Project, update and maintain them via StarTeam, and then synchronize them back to the original project source. In StarTeam, tasks are versioned but they do not branch.
Topic	A topic is very similar to a newsgroup message. Like newsgroup messages, topics can be organized into conversation threads. Because topics are artifacts, they are versioned (but not branched) and are stored in the repository with other artifacts. This allows you to capture more application lifecycle knowledge such as important discussions related to a design decision or a requirement approval.
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 audit is a read-only change event artifact that is automatically generated for other artifact changes: add, modify, delete, move, label attach, link, etc. Because audits are automatically generated and immutable, they are not really artifacts per se, but StarTeam allows you to access them with similar GUI and SDK techniques as other artifacts, so you can think of them as read-only artifacts. The generation of audits and the length of time that they are retained are configurable.

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 server-side component (SSC). Each SSC is a code library suffixed with .ssc that resides in the StarTeam Server’s installation directory. If you rename an .ssc module before the server starts, the corresponding artifact type will not be used. For example, if you want to use StarTeam as a VCS only, just rename all *.ssc modules except for file.ssc.

Back to top

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	Paths are formed by each view’s item tree. This means that folder artifacts do not define their contents. Instead, what appears inside a folder is determined by the items that refer to the folder’s item as their parent. You don’t really move artifacts—you move items. Moving an item from one folder to another causes the item’s parent to be modified—the artifact referred to by the item isn’t touched. Under the hood, items are versioned similarly to artifacts. This means that changes such as moving an item to a new folder really creates a new item revision, causing the previous item to become historic.
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 configuration timestamp to indicate whether it floats to the tip revision or is pinned to a specific revision of the referenced branch. An item’s branch-on-change (BOC) flag indicates if the referenced artifact should branch when modified through the item. For example, if an item currently refers to artifact revision 1.7, and branch-on-change is true, and an update is directed at the item, the artifact is branched by storing the updates to a new revision identified as 1.7.1.0. Additionally, the item is modified to point to the new branch (since it has a new OID), and its BOC flag is set to 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.

Back to top

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.

Back to top