Best Practices for managing externally supplied artifacts in StarTeam projects?
This article provides advice on how to manage externally
supplied artifacts, such as 3rd party libraries, that are used in
one or more projects managed in StarTeam. This advice is
particularly useful when multiple StarTeam projects are using the
same externally supplied artifacts, including when the projects may
be using different versions of the externally supplied artifacts.
Two different methods are discussed;
These methods are recommended depending on the utility required
in the projects.
First, just to get them out of the way, let"s talk about links. Since they are purely association objects, links do not change the behavior of the linked items in any way. Linking two folders, for example, does not change how the folders or the items they contain behave. As suggested in the StarTeam best practices documentation, links can be used to create cross-project relationships without actually sharing. For example, CRs in different projects can be linked as a means of documenting that they are "the same defect" or conceivably you could link a folder in project A to a folder in project B as a means to say "when the folder in A is built, the files in the linked folder in B should be checked-out as well", but this would require a custom build tool. Links don"t meet the use case discussed in this article, so links will not be recommended for this use.
Method One - Just Check Them In
The easiest way to use a third party artifact, such as a library, in multiple projects is to simply check it into each project independently. This is not as wasteful as it might sound, since the vault stores each unique file revision (each MD5) only once, the second (and subsequent) check-in of the same file merely causes the new DB file record to point to the existing archive file. In other words, checking-in the same set of files over and over does not actually increase the size of the vault.
The advantage of checking-in third party artifacts into each project is that the projects are then free to evolve independently. One project may decide, for example, to allow minor upgrades of the third party artifact to be checked-in over the top of the existing artifact. Another project might decide to put every release in a separate folder so that multiple versions of the artifacts can be used simultaneously. In StarTeam development, for example, we have Apache Xerces libraries checked into a folder called "Xerces_2.8.0". If we decide to upgrade to a new version, we install the new version in another folder, such as "Xerces_2.8.1", and we change the build process to point to the new folder. This allows us to use multiple versions of the libraries or switch back to an older version if a problem is found.
Method Two - Shared Folders
One disadvantage of independent check-ins is that it"s not easy to see which projects are using a specific artifact. If this is important, then this may be a case where sharing folders is the better approach. This process uses floating folders, so it works only if each new release is checked into its own folder (as in the Xerces case above). The process is pretty simple:
- Select the third party parent folder in the folder tree.
- Select the FILE Tab and click "All Descendants".
- Select all files in the item pane (e.g., CTRL-A).
- Right-click in the item pane and select ADVANCED | BEHAVIOUR
- Ensure that "Branch on change" is not selected, and that the Configuration is set to Floating.
- Repeat (2.) through (5.) for the folders, i.e. with the Folder tab selected.
- Since step (6.) doesn"t include the parent folder itself, right-click on the parent folder in the folder tree and perform steps (4.) and (5.) for it.
Note that sharing third party artifact files is one of the only
cases where floating shares make sense. In short, we want both
projects to always have exactly the same files, and we don"t
want one project"s file to branch by itself. Again, this
assumes that each version of the set of artifacts will be checked
into its own folder. To see all projects in which a given folder or
file is used, simply select it and click the Reference tab.