com.atlassian.bitbucket.scm

Interface PluginMergeStrategy

public interface PluginMergeStrategy

Describes a single merge strategy, which controls how commits from one line of development are applied to another. Some strategies may not "merge" at all; others might always merge, even when a merge isn't strictly necessary.

Each strategy is expected to have a localizable description and name. These values will be displayed in the UI to allow administrators to select which strategy or strategies they wish to use for their repositories. Localized values may be associated with keys by registering an "i18n" resource in atlassian-plugin.xml. The XML for such a resource looks like: <resource type="i18n" name="..." location="..."/>.

Since:

4.9

Method Summary

Modifier and Type	Method and Description
String	getDescriptionKey() A short, descriptive summary of what the strategy does, suitable for display in a space-constrained UI.
default Optional<String>	getFlag() Retrieves a flag, or series of flags, which would be familiar to users of the SCM to help identify what the strategy does by relating it to well-known command line functionality.
String	getId() Retrieves an SCM-unique identifier for the merge strategy.
String	getNameKey() A short, human-readable name for the strategy, like "Fast-forward", suitable for display in a space- constrained UI.
boolean	isDefault() Retrieves a flag indicating whether this strategy is the SCM's default, the strategy it will use if no explicit strategy is requested.

Method Detail

getDescriptionKey

@Nonnull
String getDescriptionKey()

A short, descriptive summary of what the strategy does, suitable for display in a space-constrained UI. The description should make sense to someone familiar with the SCM, but should also be informative for novices to help them make an informed decision on which strategy, or strategies, to use.

SCMs are expected to return a key, which will be used to look up a localized description, rather than a fixed-language description. Localized text can be associated with the key by registering an "i18n" resource in atlassian-plugin.xml.

Returns:

a key to look up a localized description

getFlag

@Nonnull
default Optional<String> getFlag()

Retrieves a flag, or series of flags, which would be familiar to users of the SCM to help identify what the strategy does by relating it to well-known command line functionality. Strategies are not required to provide a flag if there isn't a logical value. For example, if the strategy is implemented by extending or overriding the SCM's standard functionality, there may not be a well-known flag for it.

Implementation Note: Implementations may not return null. They are required to return Optional.empty() if there is no value. To facilitate a correct implementation, the interface defaults to returning Optional.empty(). It may be overridden for strategies with a well-known flag.

Returns:

a well-known flag, or series of flags, related to the strategy, or Optional.empty() if there isn't one

getId

@Nonnull
String getId()

Retrieves an SCM-unique identifier for the merge strategy. The identifier returned does not have to be unique across all SCMs; it only needs to be unique within the specific SCM it's returned by.

Warning: SCM implementors should choose their IDS with care because they cannot be changed. Additionally, IDs must be 255 characters or less. These IDs will be persisted by the system, to allow administrators to configure which strategy or strategies should be used for various operations (for example, when merging a pull request). Changing a strategy's ID will result in unexpected changes in behavior, and IDs longer than 255 characters cannot be persisted.

Returns:

a unique identifier for the strategy, unchanging and 255 characters or less

getNameKey

@Nonnull
String getNameKey()

A short, human-readable name for the strategy, like "Fast-forward", suitable for display in a space- constrained UI.

SCMs are expected to return a key, which will be used to look up a localized name, rather than a fixed-language name. Localized text can be associated with the key by registering an "i18n" resource in atlassian-plugin.xml.

Returns:

a key to look up a localized name

isDefault

boolean isDefault()

Retrieves a flag indicating whether this strategy is the SCM's default, the strategy it will use if no explicit strategy is requested. SCMs may only have a single default. For SCMs which support more than one strategy, exactly one may be marked as the default.

If the SCM has a well-known client, like git or hg, the default strategy for the SCM implementation is not required to be the same as the client might use. SCM implementors are free to choose whatever default they feel produces the best results for the majority of use cases. By exposing multiple strategies, administrators are free to select their own default if the SCM implementation's default is not what they're looking for.

Returns:

true if this is the default strategy; otherwise, false for all other strategies