Skip to content

Commit 26ab191

Browse files
hendrikebbershendrikebbers
committed
Version 1.0.0
1 parent 430efaf commit 26ab191

2 files changed

Lines changed: 136 additions & 1 deletion

File tree

‎docs/releases/upgrade-to-1.0.0.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Upgrade prompt: `com.open-elements:java-parent` 0.5.1 → 1.0.0
2+
3+
## Prompt
4+
5+
You are upgrading a Maven project that uses `com.open-elements:java-parent` as its `<parent>`, moving from `0.5.1` to `1.0.0`. This is the **first stable major release**, and it is **breaking**. Two things change for consumers:
6+
7+
1. **The parent no longer contributes any dependencies to its children.** In `0.5.1` the parent declared a top-level `<dependencies>` block, so every child inherited four artifacts directly on its classpath. In `1.0.0` that block is gone — children that used any of those four types must now declare them themselves.
8+
2. **A `maven-enforcer-plugin` rule now fails the build** if it runs on Maven `< 3.9.11` or Java `< 21`.
9+
10+
There are **no managed-dependency version changes** (Spring Boot stays `3.5.14`, Testcontainers stays `2.0.5`) and **no API/code changes** — this is a build-model change only. Apply exactly the changes below and nothing outside this scope.
11+
12+
### What changed in 1.0.0
13+
14+
#### Dependencies
15+
16+
Bump only the `<parent>` version of `com.open-elements:java-parent` to `1.0.0`. The **BOM-managed versions are unchanged**: `spring-boot-dependencies` stays at `3.5.14` and `testcontainers-bom` stays at `2.0.5`, both still imported via the parent's `<dependencyManagement>`. Do **not** bump those, and do **not** bump any Maven / JReleaser / CycloneDX / Spotless plugin version in the consumer — the plugin bumps in `1.0.0` are internal to the parent and have no consumer-facing effect.
17+
18+
#### Breaking: inherited `<dependencies>` removed from the parent
19+
20+
In `0.5.1` the parent declared these as a **top-level `<dependencies>` block** (not `<dependencyManagement>`), so every child inherited all four as real, resolved dependencies on its compile classpath:
21+
22+
```xml
23+
<!-- present in 0.5.1, REMOVED in 1.0.0 -->
24+
<dependencies>
25+
<dependency>
26+
<groupId>io.swagger.core.v3</groupId>
27+
<artifactId>swagger-annotations-jakarta</artifactId>
28+
<version>2.2.29</version>
29+
</dependency>
30+
<dependency>
31+
<groupId>org.jspecify</groupId>
32+
<artifactId>jspecify</artifactId>
33+
<version>1.0.0</version>
34+
<scope>compile</scope>
35+
</dependency>
36+
<dependency>
37+
<groupId>com.slack.api</groupId>
38+
<artifactId>slack-api-client</artifactId>
39+
<version>1.45.3</version>
40+
</dependency>
41+
<dependency>
42+
<groupId>org.wiremock</groupId>
43+
<artifactId>wiremock-standalone</artifactId>
44+
<version>3.10.0</version>
45+
</dependency>
46+
</dependencies>
47+
```
48+
49+
In `1.0.0` the parent declares **no** top-level `<dependencies>` at all. The accompanying `<properties>` versions were also removed (`swagger-annotations-jakarta.version`, `jspecify.version`, `slack-api-client.version`, `wiremock.version`, and the unused `junit-jupiter.version`).
50+
51+
A consumer that **used any of these types in its own source or tests** will now fail to compile (e.g. `package org.jspecify.annotations does not exist`, `package io.swagger.v3.oas.annotations does not exist`, `cannot find symbol: class WireMockServer` / `com.slack.api.*`). A consumer that never referenced them is unaffected and needs no action.
52+
53+
For each of the four that the consumer actually uses, add it back as an **explicit dependency in the consumer's own `pom.xml`**, pinning the same version that `0.5.1` provided (so behavior is byte-for-byte unchanged) and choosing the correct scope:
54+
55+
```xml
56+
<!-- Add ONLY the ones the consumer actually references -->
57+
58+
<!-- JSpecify nullness annotations (@Nullable, @NonNull) — used in main source -->
59+
<dependency>
60+
<groupId>org.jspecify</groupId>
61+
<artifactId>jspecify</artifactId>
62+
<version>1.0.0</version>
63+
</dependency>
64+
65+
<!-- Swagger / OpenAPI annotations (io.swagger.v3.oas.annotations.*) -->
66+
<dependency>
67+
<groupId>io.swagger.core.v3</groupId>
68+
<artifactId>swagger-annotations-jakarta</artifactId>
69+
<version>2.2.29</version>
70+
</dependency>
71+
72+
<!-- Slack API client (com.slack.api.*) -->
73+
<dependency>
74+
<groupId>com.slack.api</groupId>
75+
<artifactId>slack-api-client</artifactId>
76+
<version>1.45.3</version>
77+
</dependency>
78+
79+
<!-- WireMock standalone — typically test-only; use <scope>test</scope> unless
80+
the consumer genuinely references it in main source -->
81+
<dependency>
82+
<groupId>org.wiremock</groupId>
83+
<artifactId>wiremock-standalone</artifactId>
84+
<version>3.10.0</version>
85+
<scope>test</scope>
86+
</dependency>
87+
```
88+
89+
#### Breaking: build environment now enforced (Maven ≥ 3.9.11, Java ≥ 21)
90+
91+
`1.0.0` binds `maven-enforcer-plugin` to the build with a rule that fails fast on an unsupported toolchain:
92+
93+
```xml
94+
<!-- new in 1.0.0 (parent) -->
95+
<requireMavenVersion><version>3.9.11</version></requireMavenVersion>
96+
<requireJavaVersion><version>21</version></requireJavaVersion>
97+
```
98+
99+
If the consumer builds on Maven `< 3.9.11` or a JDK `< 21`, the build now stops with an enforcer error such as `Detected Maven Version: ... is not in the allowed range 3.9.11` or `Detected JDK version ... is not in the allowed range 21`. This is the intended behavior — these are the minimums the parent already targeted (`maven.compiler.source/target` were already `21`); `1.0.0` just makes the requirement explicit and hard.
100+
101+
These minimums are exposed as overridable properties, so a child that needs a **higher** floor can raise them (it cannot lower them below what the parent enforces in practice without redefining the rule):
102+
103+
```xml
104+
<properties>
105+
<enforcer.requiredMavenVersion>3.9.11</enforcer.requiredMavenVersion>
106+
<enforcer.requiredJavaVersion>21</enforcer.requiredJavaVersion>
107+
</properties>
108+
```
109+
110+
#### Additive / internal (no consumer action)
111+
112+
These changed in the parent but do not require any consumer edit: `cyclonedx-maven-plugin` `2.9.1`→`2.9.2`, `jreleaser-maven-plugin` `1.23.0`→`1.24.0`, `spotless-maven-plugin` `3.4.0`→`3.7.0`, `versions-maven-plugin` gained `<overwriteOutput>true</overwriteOutput>`, plus CI, helper-script, and `target/` artifact cleanup internal to the `java-parent` repository.
113+
114+
### Steps
115+
116+
1. In the consumer's `pom.xml`, set the `<parent>` `<version>` of `com.open-elements:java-parent` to `1.0.0`. Leave all other coordinates untouched.
117+
2. Confirm the build toolchain meets the new floor: Maven `≥ 3.9.11` and JDK `≥ 21` (check `mvn -version`). Upgrade the local/CI toolchain if either is below the minimum — do **not** weaken the enforcer rule.
118+
3. Determine which of the four removed dependencies the consumer actually references. Search the consumer's source and tests for: `org.jspecify`, `io.swagger.v3.oas` (or `io.swagger.core.v3`), `com.slack.api`, and `org.wiremock` / `WireMock`.
119+
4. For each one found, add the matching explicit `<dependency>` (from the block above) to the consumer's `pom.xml`, using the listed version and the correct scope (WireMock is normally `test`).
120+
5. Run `mvn -U clean verify` (or the project's equivalent) and confirm the project compiles, all dependencies resolve, and the test suite is green before committing.
121+
122+
### Guard rails
123+
124+
- Do **not** bump Spring Boot, Testcontainers, or any plugin version in the consumer to "match 1.0.0" — the BOM-managed versions are unchanged and the plugin bumps are internal to the parent.
125+
- Do **not** add any of the four dependencies that the consumer does not actually reference. Re-adding them speculatively re-introduces classpath bloat that this release intentionally removed.
126+
- Pin the re-added dependencies to the **exact versions listed** (the ones `0.5.1` provided) so behavior is unchanged; do not silently upgrade them as part of this bump.
127+
- Do **not** lower, disable, or `<skip>` the enforcer rule to get an older Maven/JDK to build. Fix the toolchain instead.
128+
- Add WireMock with `<scope>test</scope>` unless the consumer genuinely uses it in main source; the parent previously leaked it as compile scope, which you should not reproduce.
129+
130+
### Don't do this
131+
132+
- Do not "shim" the removal by adding the four dependencies back into `java-parent` itself, or by re-declaring a top-level `<dependencies>` block in an intermediate parent so children keep inheriting them — the removal is intentional.
133+
- Do not move the re-added dependencies into the consumer's `<dependencyManagement>` only; they must be real `<dependencies>` for the code that uses them to compile.
134+
- Do not edit, override, or delete the enforcer rule, `enforcer.requiredMavenVersion`, or `enforcer.requiredJavaVersion` to dodge the toolchain requirement.
135+
- Do not bundle this upgrade with unrelated dependency bumps, plugin changes, or feature work in the same PR.

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
<groupId>com.open-elements</groupId>
66
<artifactId>java-parent</artifactId>
7-
<version>1.0.0-SNAPSHOT</version>
7+
<version>1.0.0</version>
88
<packaging>pom</packaging>
99

1010
<name>Java Parent</name>

0 commit comments

Comments
 (0)