Best Practices for managing externally supplied artifacts in StarTeam projects?



Best Practices for managing externally supplied artifacts in StarTeam projects?


  • Product Name: StarTeam
  • Product Version: 2008
  • Product Component: External Artifacts
  • Platform/OS Version: ALL

Article Summary

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;

  • Checking in artifacts to the projects
  • Sharing artifacts into the projects

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:

  1. In the CPC, check all files of the third party artifact into the main view of the first project. Assuming that the set of artifacts has a single "parent" folder under which all subfolders and files then reside.
  2. With the first project still open, open the main view of the second project to which the set of artifacts will be shared and select


    so that both views are visible.

  3. With the CTRL key pressed, drag-and-drop the third party parent folder from the first project to the appropriate place in the folder tree in the second project where it is to be shared. All folders and files will be shared to the second project.
  4. In most cases, the files and folders will be shared with branch-on-change set and a floating configuration. If the original artifact is updated (e.g., with a bug fix), we want those changes to float immediately to the child shares, hence we need to ensure that Branch On Change is set to false on all files and folders. To do this, in the second project:
  1. Select the third party parent folder in the folder tree.
  2. Select the FILE Tab and click "All Descendants".
  3. Select all files in the item pane (e.g., CTRL-A).
  4. Right-click in the item pane and select ADVANCED | BEHAVIOUR
  5. Ensure that "Branch on change" is not selected, and that the Configuration is set to Floating.
  6. Repeat (2.) through (5.) for the folders, i.e. with the Folder tab selected.
  7. 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.

Old KB# 29334
Comment List