You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by gn...@apache.org on 2026/10/16 09:24:13 UTC

(maven) branch feature/build-report updated: feat: add reportVersion field to build-report.json

This is an automated email from the ASF dual-hosted git repository.

gnodet pushed a commit to branch feature/build-report
in repository https://gitbox.apache.org/repos/asf/maven.git


The following commit(s) were added to refs/heads/feature/build-report by this push:
     new 4d4ccfbde8 feat: add reportVersion field to build-report.json
4d4ccfbde8 is described below

commit 4d4ccfbde8f7971f81e387914eb9a1e19abdc406
Author: Guillaume Nodet <gn...@gmail.com>
AuthorDate: Fri Oct 16 11:24:03 2026 +0200

    feat: add reportVersion field to build-report.json
    
    Add "reportVersion": "1.0" as the first field in the JSON output
    so external consumers can detect format changes.
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
---
 .../apache/maven/api/build/report/BuildReport.java    | 19 +++++++++++++++++++
 .../maven/internal/build/BuildReportJsonWriter.java   |  1 +
 .../maven/internal/build/DefaultBuildReport.java      |  6 ++++++
 3 files changed, 26 insertions(+)

diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/build/report/BuildReport.java b/api/maven-api-core/src/main/java/org/apache/maven/api/build/report/BuildReport.java
index f8d6088ae4..c6fbc6aa6a 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/build/report/BuildReport.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/build/report/BuildReport.java
@@ -47,6 +47,25 @@
 @Immutable
 public interface BuildReport {
 
+    /**
+     * Semantic version of the report format (e.g. {@code "1.0"}).
+     * <p>
+     * Versioning policy:
+     * <ul>
+     *   <li><b>Minor</b> increments (1.0 &rarr; 1.1) are purely additive &mdash;
+     *       new fields may appear, but existing fields keep their name, type, and
+     *       meaning. Consumers that ignore unknown fields are forward-compatible.</li>
+     *   <li><b>Major</b> increments (1.x &rarr; 2.0) signal a breaking change &mdash;
+     *       fields may be removed, renamed, or change type. Consumers should check
+     *       the major version and refuse to parse an unsupported major.</li>
+     * </ul>
+     *
+     * @return the semver report version string, never {@code null}
+     * @since 4.1.0
+     */
+    @Nonnull
+    String reportVersion();
+
     /**
      * The invocation context of this build: flags, properties, and platform settings
      * that were active when the session started.
diff --git a/impl/maven-core/src/main/java/org/apache/maven/internal/build/BuildReportJsonWriter.java b/impl/maven-core/src/main/java/org/apache/maven/internal/build/BuildReportJsonWriter.java
index b94d8cb202..3c39146ac4 100644
--- a/impl/maven-core/src/main/java/org/apache/maven/internal/build/BuildReportJsonWriter.java
+++ b/impl/maven-core/src/main/java/org/apache/maven/internal/build/BuildReportJsonWriter.java
@@ -49,6 +49,7 @@ static String toJson(BuildReport report) {
 
     private static void writeReport(StringBuilder sb, BuildReport report, int indent) {
         sb.append("{\n");
+        writeField(sb, indent + 1, "reportVersion", report.reportVersion());
         writeField(sb, indent + 1, "formatVersion", report.formatVersion());
         writeField(sb, indent + 1, "status", report.status().name());
         writeField(sb, indent + 1, "duration", report.duration().toString());
diff --git a/impl/maven-core/src/main/java/org/apache/maven/internal/build/DefaultBuildReport.java b/impl/maven-core/src/main/java/org/apache/maven/internal/build/DefaultBuildReport.java
index 0eed279fb6..ae0213a554 100644
--- a/impl/maven-core/src/main/java/org/apache/maven/internal/build/DefaultBuildReport.java
+++ b/impl/maven-core/src/main/java/org/apache/maven/internal/build/DefaultBuildReport.java
@@ -50,8 +50,14 @@ record DefaultBuildReport(
         List<LogEvent> output)
         implements BuildReport {
 
+    private static final String REPORT_VERSION = "1.0";
     private static final int FORMAT_VERSION = 1;
 
+    @Override
+    public String reportVersion() {
+        return REPORT_VERSION;
+    }
+
     @Override
     public int formatVersion() {
         return FORMAT_VERSION;