How to Handle Cross-Project File Dependencies

When projects are highly cohesive, cross-project dependencies will be minimal, yet cross-project file relationships may still occur. Some files, either authored or generated, may need to be used in multiple projects.

The impulsive way to handle this situation may be to share the co-dependent files from one project to another. On the surface, this approach works, but experience has shown that cross-project sharing is problematic for several reasons:

If a shared item’s behavior is configured to “floating”, changes from the parent project flow into the child project immediately, sometimes at inconvenient times. Many StarTeam users find that they need to manage the update propagation on a more scheduled basis.
If a shared item’s behavior is configured to a specific timestamp, it must be occasionally adjusted to allow updates to propagate. This makes the shared item read-only, and continually adjusting the configuration timestamp for a large number of shares can become burdensome.
If a shared item’s branch-on-change property is set to “true” (perhaps accidentally), and a change is made to the child share, the object will branch in the child project. This severs automatic promotion of changes from the parent item to the child share. If the child share is a folder, an innocuous change such as modifying the working folder will cause the folder object to branch
When an update is made to an item, the entire share tree must be locked. As the share tree grows, update performance is impacted proportionately.
Normally, when obsolete views and projects are deleted, the StarTeam purge utility can be used to return unused database records and archive files. However, shares used by a deleted project or view can prevent the purge utility from achieving the expected reduction in database and archive size. In short, it might not be possible to reduce the size of servers that use cross-product sharing.

Because of these reasons, other techniques have proven to be more effective at handling cross-project file dependencies. Below are some alternatives to sharing that work in different situations. In the end, shares still may be the most appropriate way to expose files from one project to another, but the approaches below should be considered first.

Deployment Approach

If a project “owns” a set of files that must be checked into other projects, you can establish a process in which the files are periodically “deployed”. This means that the file set is checked into the target project(s) on an as-needed basis, perhaps by a script. Often, a build script is a good place to embed the deployment task, especially if the file(s) to be deployed are generated by the build. Keep in mind that checking in the same file multiple times does not (generally) increase the size of the vault, each unique file revision is only stored once.

Configuration Approach

Sometimes the co-dependent files don’t need to be checked into each project, but they need to participate in a common process such as a build or delivery process. In these cases, a simple configuration file (for example, XML) can be constructed that defines the files that participate in the process. If the file is checked into an established location and updated when the configuration changes, then build, release, or other scripts can check out the configuration file, parse it, and base their processing on its instructions.

Link Approach

In lieu of shares, links can be used to connect objects across servers. Links do not possess many of the problems exhibited by shares, and they can be pinned, unpinned, and moved to refer to different object revisions. The downside of using links is that they are un-typed and possess no properties other than a link comment to identify their purpose.