public interface

PluginMergeStrategies

com.atlassian.bitbucket.scm.PluginMergeStrategies

Class Overview

Describes an SPI for allowing SCMs to expose user-selectable merge strategies. In addition to exposing a set of SCM-specific merge strategies, SCMs must also provide a help topic/URL to document how each strategy works.

This SPI is an optional part of the SCM contract. SCMs which implement merge strategies should ScmFeature#MERGE_STRATEGIES enable the feature, or their strategies will not be used.

Summary

Public Methods
@Nonnull String getHelpTopic()
Retrieves a help topic, which is used to com.atlassian.bitbucket.help.HelpPathService#getPageUrl look up a URL for additional documentation about the available merge strategies.
@Nonnull Set<PluginMergeStrategy> getStrategies()
Retrieves the set of supported merge strategies.

Public Methods

@Nonnull public String getHelpTopic ()

Retrieves a help topic, which is used to com.atlassian.bitbucket.help.HelpPathService#getPageUrl look up a URL for additional documentation about the available merge strategies. While each strategy has its own description, that is intended to be a short summary of how the strategy works. The help documentation is expected to provide a richer, more in-depth explanation of what the available strategies do.

There are two approaches for implementing this method:

  • Return a key, like "myscm.mergestrategies.help".
    • The value can be defined by registering an "i18n" resource in atlassian-plugin.xml. The XML looks like: &lt;resource type="i18n" name="..." location="..."/&gt;
    • If the SCM is already registering an "i18n" resource, the key/value can simply be added to the existing resource; no need to define a separate one.
  • Return a fixed URL.
    • If the com.atlassian.bitbucket.help.HelpPathService#getPageUrl(String) URL lookup doesn't return a value, the system assumes the topic value is the URL to use.
    • This approach doesn't require an "i18n" resource, for SCMs which don't have one.

Returns
  • a topic, used to look up a help URL, or the help URL to use

@Nonnull public Set<PluginMergeStrategy> getStrategies ()

Retrieves the set of supported merge strategies. The returned set may be fixed, or it may vary (for example, some merge strategies might only be available when a specific version or version range of the SCM is installed).

The returned Set is required to contain at least one strategy, and implementors are strongly encouraged to support at least two. Merge strategies are not actually "selectable" when there is only one option.

Returns
  • a set containing one or more available strategies