-
Notifications
You must be signed in to change notification settings - Fork 1
Dependency Rules
Dependency rules are declared in a dependencyfile.json descriptor.
The plugin locates the descriptor through an ordered lookup:
-
the project root
-
.idea/
For trusted projects only, the lookup also includes:
-
the parent directory of the project root
-
the user home directory
The first descriptor found is used.
|
Note
|
Pure plugin dependencies are not subject to inferred semantic-version upgrade limits, because plugin dependency relationships are separate from regular dependency management. Explicit names, generations, and upgrades limits still apply.
|
|
Note
|
When a dependencyfile.json is present, upgrade suggestions can derive semantic-version-based strategy limits from the project version in addition to the rules declared in the descriptor.
Basic newer-version suggestions do not require a descriptor.
When the project version is a service release, that is, a three-segment version with a non-zero patch segment such as x.y.1, only patch and release upgrades are suggested; otherwise all upgrade strategies are permitted.
The semver attribute described below controls this derivation.
|
The descriptor uses a JSON format with rules declared under artifacts or branches, as shown in the following example:
{
"artifacts": {
"org.springframework:*": { "name": "Spring Framework", "generation": "7.0.x" },
"org.junit:*": "5.13"
},
"branches": {
"3.5.x": {
"artifacts": { "org.springframework:*": "6.2.x" }
},
"2.*.x": {
"upgrades": ["patch", "minor"],
"artifacts": { "org.springframework:*": "5.3.x" }
}
}
}The root object can contain the attributes listed in the following table:
| Name | Type | Purpose |
|---|---|---|
|
Boolean |
Controls whether semantic-version-based upgrade-strategy limits are derived from the project version.
|
|
Object |
The default artifact rules. They apply when no branch rule matches and are inherited by branch rules for artifacts that the branch does not declare itself. |
|
Object |
Branch rules, keyed by branch or project-version pattern. Branch-level artifact rules take precedence over default artifact rules. |
Each entry in an artifacts object maps an artifact pattern to a rule.
The pattern matches Maven-style coordinates and supports * wildcards.
For example, org.springframework:* matches every artifact in the org.springframework group, spring- matches artifacts by name across all groups, and matches all artifacts.
Both : and / are accepted as separators between group and artifact.
The rule value is a generation string, an array of generations, or an object. The string form is a shortcut for an object that declares a single generation, and the array form lists the permitted generations:
"org.junit:*": "5.13"
"org.springframework:*": ["6.5.x", "7.0.x"]The object form can contain the attributes listed in the following table:
| Name | Type | Purpose |
|---|---|---|
|
String |
A display name to use in inspection messages instead of the artifact pattern. Optional. |
|
String or Array |
The permitted generation, or an array of permitted generations.
Optional.
An object with only a |
When several patterns match the same artifact, the most specific rule wins.
An exact group:artifact pair wins over an exact artifact name, followed by an artifact wildcard, a group:artifact pattern with wildcards, and finally the * catch-all.
A generation is a project development line expressed as a literal version prefix.
Supported inputs include major lines such as 6, minor lines such as 6.0 or 6.0.x, and exact versions such as 6.0.1.
A trailing .x is equivalent to omitting it.
The value * accepts any version.
A version satisfies a generation when it is equal to the prefix or starts with the prefix followed by a dot.
A generation array lists several development lines, such as ["6.5.x", "7.0.x"], and a version matches when it satisfies any listed generation.
If an array contains *, the rule is unconstrained.
Each key in the branches object is a pattern that supports wildcards.
The pattern is matched against the current Git branch name first.
If no branch pattern matches the current branch, the pattern is matched against the project version.
For prefixed project versions, matching checks both the displayed version and the unwrapped inner version, so v2.1.0 can match v2. and 2.*.
A pattern such as 2.*.x can therefore match both maintenance branches and projects whose version belongs to that line.
When several patterns match, the most specific pattern wins.
Each branch object can contain the attributes listed in the following table:
| Name | Type | Purpose |
|---|---|---|
|
Array |
The upgrade strategies permitted on matching branches. When omitted or empty, all strategies are permitted. |
|
Object |
Artifact rules for matching branches, using the same format as the top-level |
Branch-level artifact rules take precedence over top-level artifact rules.
An artifact without a matching branch-level rule inherits the default artifact rule, if any.
Inherited rules remain subject to the branch’s upgrades limits.
The upgrades array accepts the values listed in the following table.
Values are matched case-insensitively.
Unknown values are ignored.
| Value | Purpose |
|---|---|
|
The newest GA release within the same major and minor line. |
|
The newest GA release with the same major version and a higher minor version. |
|
The newest GA release with a higher major version. |
|
The newest GA release, regardless of version boundaries. |
|
The newest preview release, such as a milestone or release candidate, that is newer than the current version. |
|
The GA release that finalizes a snapshot or preview version.
For example, |
Parsing is lenient.
An artifact or branch entry that cannot be interpreted is logged and skipped rather than failing the whole descriptor.
Generations are salvaged entry by entry: an invalid generation is dropped, and a rule whose generations all fail to parse stays present but unconstrained rather than being removed.
Unknown upgrade values and a non-boolean semver value are ignored.
A partially valid descriptor therefore still contributes the rules it can express.
A descriptor whose top-level value is not a JSON object yields no rules.