How Release Management Handles Shared Content

By default, creating a new product or release or branching a release support reuse of referenced objects already in another release in the Products cabinet.

One of the goals of using a CCMS and structured documents is to reuse content rather than duplicating content. In the Release Management feature, Astoria makes duplicate copies of content to support parallel concurrent development. However, where content has been created especially for reuse, such as corporate boilerplate topics, conref targets, images, or glossary entries, creating duplicate copies of those objects contradicts the goal of reuse. To ensure appropriate reuse of shared content, the Release Management feature allows new releases to reference shared content that already exists in the Products cabinet.

Referenced assets outside of the current release are called shared content. When you create a release or product, you seed the content of the release by specifying Documents to add to release. These documents and all of the assets (documents, files, and external files) that they reference will be included in the release. Astoria remembers this list of documents and assets—both the location in the regular cabinet hierarchy that they came from, and the location in the release they were copied to.

Later, you create another release or product. If you allow linking to shared release content (that is, you leave the Don't Link to Shared Release Content check box cleared), you can point to another release to look for shared content to link to. Next to the When Importing and Linking to Shared Content, Look next in Release: field, click Browse, then navigate to and select the desired release to link to. If any of the previously seeded assets (from the regular cabinet hierarchy) are encountered, Astoria will create references to the seeded copy in the selected release and will not clone copies in the new release. However, if no shared content assets are found, the referenced assets are created in the new release. See About Looking to Another Release for Linking to Shared Content. When you branch a release, the dialog includes a check box, Clone Shared Content. The default for this check box is that it is cleared; that is, the default behavior is for referencing objects to link to objects already in an existing release in the Products cabinet instead of cloning them in the new product or release. However, references to shared content that exists only within a branch are cloned.

Important: If referenced objects were once created in the Products cabinet, but were later deleted and placed in the wastebasket, and you use the default check box values for shared content when creating a release, references will point to the object in the wastebasket, resulting in errors or failed jobs. To avoid this problem, ensure that deleted objects that would otherwise be referenced in the Products cabinet are permanently destroyed before creating a release. See About Deleted Objects in a Release.

Example of Seeding with Reusable Content

Suppose you have a folder in a regular repository cabinet that holds container DITA topics that include only conref targets that are referenced by a large number of production topics in several product lines. One of these topics is a DITA task topic that has over 25 reusable step element targets.
  • Some of the step command elements contain hrefs to image files of user interface icons.
  • Some of those step info elements contain a note element that conrefs another container topic with targets for notes and cautions.
  • Other step info elements contain xrefs to production topics.
If you create a Product and seed Release A by selecting only the container task topic, the Release A will produce a folder structure that contains:

Subsequently you seed Release B by selecting just the bookmap for an individual product in that product line, and leave the Don't Link to Shared Release Content check box cleared. Release B will produce a folder structure that contains everything referenced by the selected bookmap except anything that was seeded in Release A. Anything in Release B that referenced any object that was seeded in Release A will reference that object in Release A.

Finally, you branch Release B into Release C and leave the Clone Shared Content check box cleared. Release C will produce a folder structure identical to Release B. Anything in Release C that referenced any object that was seeded in Release A will reference that object in Release A.

Determining How Shared Content Was Created

Use the View Activity command on a release to see the shared content check box options used to create the release. This information is also included in the email notification sent to the user creating the release.

Use the List What Used, Show What Used, or Locate commands on shared content objects referenced by structured objects in a release folder to trace their location or ancestry in the Products cabinet hierarchy.