You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add support for the `independent` version strategy, allowing sub-modules in a multi-module Maven project to be versioned independently of each other.
6
+
7
+
The prepare→release handoff has moved from the single-line `.changeset/VERSION` file to a per-artifactId map in `.changeset/VERSIONS` (plural). The current version is now read directly from each module's `pom.xml` rather than from the version file. Any pre-existing `.changeset/VERSION` file is no longer consulted and can be safely deleted.
Copy file name to clipboardExpand all lines: README.md
+128-4Lines changed: 128 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,96 @@ users recognize the ways of working and feel at home.
8
8
9
9
This is it, at the moment. Stay tuned for more docs later on, thanks!
10
10
11
+
## Versioning strategies
12
+
13
+
By default every module in the Maven reactor shares one version (the **fixed** strategy) — any changeset bumps every module
14
+
to the same new version. This matches the typical Maven convention where child modules inherit `<version>` from the parent.
15
+
16
+
To opt into per-module versioning, drop a `.changeset/config.json` at the reactor root:
17
+
18
+
```json
19
+
{
20
+
"versioning": "independent",
21
+
"linked": [["module-a", "module-b"]],
22
+
"fixed": [["module-c", "module-d"]]
23
+
}
24
+
```
25
+
26
+
-**`fixed` (default)** — entire reactor bumps as one.
27
+
-**`independent`** — each Maven module tracks its own version. Optional `linked` and `fixed` arrays group some modules:
28
+
-**`linked` group**: members that have changesets bump together to the same new version; members without changesets stay where they are. The new version is the *highest current version in the group* bumped by the *highest level among changesets touching the group*.
29
+
-**`fixed` group**: every member of the group bumps together, even members without their own changesets.
30
+
31
+
A changeset's frontmatter lists modules by `artifactId`:
32
+
33
+
```
34
+
---
35
+
"module-a": minor
36
+
"module-b": patch
37
+
---
38
+
39
+
Description of the change.
40
+
```
41
+
42
+
The same `artifactId` cannot appear in more than one group; that is a config validation error.
43
+
44
+
### Independent versioning and `<version>` declarations
45
+
46
+
For `independent` (or `linked` / `fixed` sub-groups) to actually update individual submodule versions, each Maven submodule
47
+
must declare its own `<version>` in its `pom.xml`. Submodules that inherit `<version>` from the parent only bump together
48
+
with the parent.
49
+
50
+
## BOM (Bill of Materials) support
51
+
52
+
If your reactor contains a BOM — a `pom`-packaged module whose `<dependencyManagement>` pins sibling modules' versions via
53
+
`<properties>` (the Spring Boot convention) — opt in via `.changeset/config.json`:
-**The BOM auto-bumps** at the max level of any tracked module's bump (any reactor module that pins through the BOM's
68
+
`<dependencyManagement>`). Explicit changesets targeting the BOM still work — they combine with the synthesized level.
69
+
-**The BOM's `<properties>`** that pin sibling versions are rewritten on `prepare` (to the next `-SNAPSHOT`) and on
70
+
`release` (to the release version). The mapping is discovered by walking the BOM's `<dependencyManagement>`; you don't
71
+
have to name properties by any convention.
72
+
-**`consumerParent`** (optional) is the module a consumer sets as their `<parent>`. It typically has no `<version>` of its
73
+
own and inherits from the BOM via Maven parent inheritance. When set, it is *excluded* from the plan (no own bump) and is
74
+
used as the changelog header so consumers see entries named after the artifact they actually pin. Its `<parent>`
75
+
reference is updated when the BOM bumps. Validation: the artifactId must exist in the reactor, and if it declares its own
76
+
`<version>` it must match the BOM's.
77
+
-**Changelog rendering** in BOM mode collapses to a single top-level release header, with one sub-section per bumped
78
+
module (including the BOM, which gets a synthesized `Pinned version updates` block listing the new sibling versions).
79
+
80
+
### Releasing a starter without cutting a BOM release
81
+
82
+
Pass `-DskipBom=true` to `changesets:prepare` to bypass BOM behavior for that invocation. The starters bump as in plain
83
+
independent mode, the BOM's pom is left untouched (version *and* pinned properties), and the changelog falls back to the
84
+
standard per-module sections. The `bom` block in `.changeset/config.json` stays in place — `skipBom` is a per-run override,
85
+
not a config change. Use it when you want to ship a quick starter patch between full BOM releases.
86
+
87
+
## How `prepare` and `release` interact
88
+
89
+
`changesets:prepare` (aggregator goal, runs once at the reactor root) reads all changesets in `.changeset/`, computes a new
90
+
version per affected module, writes the new release versions to `.changeset/VERSIONS` (a properties file keyed by
91
+
artifactId), updates each affected submodule's pom to the next `*-SNAPSHOT`, and prepends a release block to the root
92
+
`CHANGELOG.md`.
93
+
94
+
`changesets:release` reads `.changeset/VERSIONS` and writes each module's pom to its release version. The `.changeset/VERSIONS`
95
+
file is the handoff between the two goals.
96
+
97
+
> **Upgrading from an earlier version:** the previous single-file `.changeset/VERSION` (uppercase, no `S`) is no longer read
98
+
> or written. The current version is now taken from each module's `pom.xml` directly, and the prepare→release handoff lives
99
+
> in `.changeset/VERSIONS`. If you have a leftover `.changeset/VERSION` file, it is unused and safe to delete.
100
+
11
101
## Dependency updates
12
102
Due to the way automated dependency update bots like Dependabot and Renovate work, there is often a large influx of automated changesets that are not easy to merge into the normal changelog. They can also be the source of an unwanted amount of noise in the changelog.
13
103
@@ -26,17 +116,32 @@ Dependencies that have been updated to new versions multiple times between relea
26
116
27
117
## Release Maven Plugin Integration
28
118
29
-
To delegate versioning to the Release Maven Plugin, you can use the `ChangesetsVersionPolicy` together with the `useReleasePluginIntegration` flag:
119
+
You can hand versioning off to the maven-release-plugin by wiring in `ChangesetsVersionPolicy`.
30
120
31
-
```
121
+
### When to use it
122
+
123
+
**Recommended:** fixed versioning (the default) — single-module or multi-module. Every module bumps together to one
124
+
version, one tag, one release commit.
125
+
126
+
**Not recommended:** independent versioning. Maven-release-plugin's model is *release the whole reactor atomically* —
127
+
every reactor module gets a release version, a tag, and a next-dev bump, whether it was targeted by a changeset or not.
128
+
That fights the point of `independent`, where you only want to release modules that actually changed. For independent
129
+
versioning, use plain `changesets:prepare` + `changesets:release` (see [How `prepare` and `release` interact](#how-prepare-and-release-interact))
130
+
and release-plugin is not recommended.
131
+
132
+
### Setup
133
+
134
+
Configure both plugins in the reactor POM:
135
+
136
+
```xml
32
137
<build>
33
138
<plugins>
34
139
<plugin>
35
140
<groupId>se.fortnox.changesets</groupId>
36
141
<artifactId>changesets-maven-plugin</artifactId>
37
142
<version>${changesets.plugin.version}</version>
38
143
<configuration>
39
-
<useReleasePluginIntegration>true</useReleasePluginIntegration> <!-- Disables version updates in prepare goal -->
0 commit comments