PDE/Importing SCMURLs

Overview

SCM URLs describe the location of source code in a repository. For example, an SCM URL can be used to describe the location of a project in CVS that corresponds to a bundle in Eclipse. The SCM URL format is described here.

In Eclipse 3.6, support was added to PDE/Build to embed source repository information in bundle manifests during the build process and support was added to PDE/UI to import bundles from repositories. Following is an example manifest header describing the location of the source for the org.eclipse.debug.core bundle:

• Eclipse-SourceReferences: scm:cvs:pserver:dev.eclipse.org:/cvsroot/eclipse:org.eclipse.debug.core;tag=v20100820

The 3.6 implementation of importing bundles in PDE/UI is based on two internal extension points and internal API interfaces. During 3.7, PDE would like to create official public API that can be used.

3.6 Implementation

The 3.6 implementation for importing bundles from repositories is based on the following (internal) extension points:

• org.eclipse.pde.core.bundleImporters - Extensions contribute delegates that when given a set of bundle manifest headers can return a corresponding set of opaque bundle import description objects that can later be imported. Extensions provide an implementation of IBundleImportDelegate (defined in org.eclipse.pde.internal.core.importing.provisional).
• org.eclipse.pde.ui.bundleImportPages - Extensions contribute one or more wizard pages used to configure bundle import description objects before import. For example, the existing implementation provides a page that allows the user to import specific project versions or from HEAD.

The current import implementation works as follows:

• PDE parses bundle manifests in the target platform and passes each bundle manifest to each bundleImporter extension.
• Each bundleImporter extension returns a set of bundle import descriptions for manifests that it is capable of importing
• Bundles that can be imported are displayed in the wizard for selection
• The user selects the bundles to import
• A wizard page allows the user to select specific versions (as defined in the SCMURLs) or to import from HEAD
• On finish, the configured set of bundle import descriptions are passed to the bundleImporter extensions to be imported
• The CVS bundle importer builds a .psf format string representing what's to be imported and passes it off to the CVS for import

The cons of the current implementation are:

• SCM URL importing is limited to PDE - it would be more flexible to offer an API at the team level.
• PDE needs to understand and manipulate strings in the .psf format, which is intended to be opaque.
• Each team provider needs to contribute to PDE extensions if they want their repository to be supported.

3.7 API Proposal

In 3.7, PDE would like to maintain the current level of function and support a public API for bundle importing. As noted in bug 195729, Martin points out that it would "feel more natural if PDE knew how to extract the SCMURL from the Manifest, then the team provider knew how to materialize the SCMURL into a team project set."

The import scenario in 3.7 could work as follows:

• PDE parses bundle manifests extracting all EclipseSourceReference headers - specifically headers that use SCM ULRs. PDE analyzes the SCM URLs to determine the set of SCM providers that are referenced (cvs, svn, etc).
• PDE asks team for RepositoryProviderType's that support the referenced SCM providers.
  • Currently, RepositoryProviderType's may optionally specify a "fileSystemScheme" attribute in their extension, so this may already be supported. However, it's not clear if SCM provider tags map to this existing attribute. New API may be required for this.
• For each SCM URL, PDE asks the associated RepositoryProviderType's ProjectSetCapability for a project reference string for each SCM URL.
  • There may be existing API for this, but implementation would need to be enhanced to handle the SCM URL format. The existing API is org.eclipse.team.core.ProjectSetCapability.asReference(URI, String).
• Addition API/UI would need to provided to allow users to specify importing from HEAD vs. specific versions. It could make sense for specific team implemenations to provide wizards that allow further configuration when importing project references. Since the project references are opaque, this configuration should be provided at the team level.