Understanding Upgrade suggestions

Upgrade Suggestions

When Dependency Assistant finds newer releases for a dependency, it does not only offer the newest version it can find. It classifies releases into upgrade strategies, keeps the available strategies selectable, and uses the first applicable strategy as the default.

This page describes the strategies, the default order, and how dependency rules and vulnerability checks can add remediation targets.

Version Terms

release: A general-availability version intended for production use. Examples include 3.9.9, 6.0.0, and 2025.0.1.
preview: A milestone or release candidate published before a final release. Examples include 6.1.0-M1 and 6.0.0-RC1.
snapshot: An in-development build that can change over time. An example is 6.0.0-SNAPSHOT.

A version number is interpreted as major.minor.patch. A patch upgrade stays within the same major.minor line. A minor upgrade stays within the same major line. A major upgrade crosses to a newer major line.

Named release trains, such as Bismuth-SR1, are handled as a separate versioning scheme. Calendar-style versions such as 2025.0.1 are numeric versions. Upgrade suggestions stay within the current versioning scheme; they do not automatically migrate from one scheme to another.

Upgrade Strategies

For a dependency, the plugin can offer the strategies listed in the following table:

Strategy	Target
`patch`	The newest non-preview release in the same major and minor line. For example, `3.9.6` can upgrade to `3.9.9`. This is the smallest regular upgrade step.
`minor`	The newest non-preview release in the same major line with a higher minor version. For example, `1.0.0` can upgrade to `1.5.0`.
`major`	The newest non-preview release in a higher major line. For example, `1.0.0` can upgrade to `3.0.0`.
`latest`	The newest non-preview release in the current versioning scheme, regardless of major or minor boundaries.
`preview`	The newest preview release, such as a milestone or release candidate, that is newer than the current version. For snapshots, the plugin first looks for a non-snapshot preview in the same major and minor line.
`release`	The GA version that finalizes the current snapshot or preview version. For example, `3.9.6-SNAPSHOT` or `3.9.6-M1` can upgrade to `3.9.6`. This strategy is not used when the current version is already stable.
`safe`	A remediation target for vulnerable dependencies. When the current version is known to be vulnerable and a newer checked release in the same versioning scheme is clean, the plugin can pin that release as the Safe Version. This depends on vulnerability data being available.
`rule`	A remediation target for dependency rules. When the current version violates a governing dependency rule and a compliant cached release exists, the plugin can pin the lowest matching compliant release as a rule-alignment target.

Preview and snapshot versions are never targets of patch, minor, or major suggestions. Those strategies always target stable releases.

Dependency Rules

A dependencyfile.json descriptor can limit which regular upgrade strategies are available for a dependency or branch.

For example, a branch rule can restrict suggestions to patch and minor upgrades:

{
  "branches": {
    "2.*.x": {
      "upgrades": ["patch", "minor"]
    }
  }
}

When such a rule matches, the plugin still classifies available releases in the same way, but regular suggestions outside the permitted strategies are filtered out. For example, if a branch permits only patch and minor, a newer major release is not offered for that branch.

Dependency rules can also constrain an artifact to a generation. Generation constraints are evaluated as rule compliance. They do not hide every out-of-generation release from every release list, but a violation can add a rule remediation target when a compliant release is known.

The presence of dependencyfile.json is not required for basic newer-version suggestions. The descriptor adds governance rules and can enable project-version-derived strategy limits.

For the descriptor format, see Dependency Rules.

Recommended Upgrade

When more than one upgrade strategy applies, the first applicable strategy becomes the default. Regular suggestions are computed in this order:

patch
minor
major
latest
preview
release

Remediation targets are shown before regular targets when they are present:

safe
rule
regular strategies in the order above

The default is therefore conservative for ordinary upgrades, but a known vulnerability or rule violation can move a remediation target to the front.

Examples

In each example, the block shows the full set of versions known to the plugin, with the current version marked. The plugin offers fewer upgrade suggestions than the number of available versions.

Service Releases

Service releases are bug-fix versions within the same major and minor line. When a newer service release is available, a patch upgrade is the default regular suggestion.

Patch Upgrade with Larger Alternatives

Available versions, current 3.9.6:

Major ->  4.0.0
Minor ->  3.11.0
          3.10.0
Patch ->  3.9.9
          3.9.8
          3.9.7
          3.9.6   <- current
          3.9.5
          3.9.0-M1

From current version 3.9.6, the plugin suggests:

patch upgrade to 3.9.9. Intermediate releases are skipped so the suggestion targets the most recent bug-fix release with minimal version-line change.
minor upgrade to 3.11.0. When several newer minor lines are available, the plugin suggests the newest one.
major upgrade to 4.0.0.
latest upgrade to 4.0.0. This can duplicate another strategy target.
preview upgrade when a newer preview exists.

Preview Versions

Preview suggestions can be offered for stable, preview, or snapshot current versions when a newer preview exists. release suggestions are used only to finalize a preview or snapshot current version.

Snapshot With Release and Patch Targets

Available versions, current 3.9.6-SNAPSHOT:

Minor ->    3.10.0
Patch ->    3.9.9
            3.9.7
Release ->  3.9.6
            3.9.6-SNAPSHOT   <- current
            3.9.5

From current version 3.9.6-SNAPSHOT, the plugin suggests:

patch upgrade to 3.9.9. This is the default regular suggestion because patch is first in the regular order.
minor upgrade to 3.10.0.
release upgrade to 3.9.6, finalizing the snapshot to its matching stable release.

Remediation Targets

When vulnerability data is available and the current version is vulnerable, the plugin can offer a safe suggestion. It is the lowest newer release in the current versioning scheme whose vulnerability result is clean.

When a dependency rule is present and the current version violates it, the plugin can offer a rule suggestion. It points at a cached release that satisfies the governing rule.

Both remediation targets are conditional. If the required scan result or compliant release is missing, no remediation suggestion is shown.