SCM Drill Down Scenarios

The scenarios described here involve read-only exploration of an SCM repository, including browsing through the contents of specific SCM configurations.

These use cases combine and replace the two previously described scenarios of build integration and work item integration, eliminating features that the workgroup has ruled out of scope for the first revision of OSLC SCM services.

The proposed SCM services would include navigation between the various SCM elements (baselines, change sets, version-controlled files, directories, and symlinks, etc.), in at least the downward direction. Bidirectional navigation is also useful, but might not be needed for this initial scenario of a drill-down report.

It is not yet defined how such navigation should be extended to other OSLC areas, such as change management, requirements management, and quality management, etc., but such navigation is highly desirable; there is significant extra value in a report that shows the changes between baselines in terms of defects fixed, requirements satisfied, tests passed, etc.

Drill-Down View and Source Code Browser

An application wishes to provide an interactive drill-down view. The user is given the opportunity to identify a specific baseline or to select one from the results of a query. Two initial views are possible; one shows the members of the selected configuration in terms of a tree of directories and files, while another shows the change sets included in that baseline. In the file tree view, the user may click on the typical expansion triangles or icons to navigate through the directory structure. In the change set view, the expansion triangles allow navigation to the files and directories associated with those change sets. The view allows users to see properties of any of the objects, including the contents of files, and the changes made to directories and files between the selected configuration and some previous configuration.

A user would also wish to see a summary of the changes made between two baselines.

Code Review

An application wishes to provide a code review tool. The user identifies one or more change sets by name, or by selecting from the results of a query, or by using OSLC CM services to find the change sets associated with a task or change request. The tool finds the directories and files associated with these change sets, the properties of those new or modified versions, and the changes made in them. The tool reviews these changes and produces a report that might be used to asses the quality and risk of the changes.

Traceability from Requirements to Code

An client needs to prove traceability down through requirements, change requests, change sets, to actual code changes. See the OSLC Requirements Management and Change Management specifications for how that traceability is provided from requirements to change requests to change sets; the OSLC SCM domain provides the ability to navigate from a change set to the associated objects in SCM, and the changes made in those objects.

Having found one or more change sets related to the starting requirement or change request, the client needs to find the baselines containing these change sets (if any).

Required SCM Services

The scenarios above suggest the following set of required SCM services:

• Query for baselines with some properties, as discussed below
• Query for baselines containing a given change set
• Find a baseline by URL (obtained from the above query, or possibly through a link from some other OSLC service)
• Get the properties of a baseline, including if available:
  • the identity of the user who created the baseline
  • date and time of creation
  • comments or description
  • baseline status
  • stream, activity, branch, or release
  • build number or identity
  • build bill of materials
• Get the members of a baseline; the result would show the hierarchical structure of the directories, links, and files in the baseline, with the ability to inline selected properties of those objects, including if available:
  • identity of the user who last changed the file
  • data and time of last file modification
  • modification comments
  • time the file was included in the configuration
  • file type and encoding
  • the identities of any associated change sets
• Get the contents of a file or the target of a link
• Get a list of the members of a directory
• Find a change set by URL (possibly obtained from a work item, requirement, or test case link)
• Get the version-controlled objects associated with a change set, with the ability to inline properties as for the baseline members report
• Report on the differences between two baselines
  • In terms of change sets fully added, change sets fully removed, and change sets otherwise modified
  • In terms of files, links, or directories that were added or removed, or whose version differs
• Report on the differences between two versions of a file; the result is an XML representation of a line-based diff
• Test if a given change set is fully included, partially included, or not included in a given baseline

When identifying baselines, we should allow for explicitly named baselines and for selection from query results. Service providers will differ in their query capabilities, but some typical queries might include the ability to find:

• recently created baselines
• the baseline that is the immediate predecessor of some other identified baseline
• the first (oldest) baseline in some given branch or stream
• the most recent baseline in some given branch or stream
• the last baseline before, or the first baseline after, some specific point in time in some given branch or stream