From 1497c91035db1c33ce7603639c9626288eb72b92 Mon Sep 17 00:00:00 2001
From: "Piotr P. Karwasz" <piotr.github@karwasz.org>
Date: Tue, 5 Nov 2024 09:27:02 +0100
Subject: [PATCH] Document API compatibility checks

This documents the existence of the BND Baseline API compatibility checks and how to fix the generated errors.
---
 BUILDING.adoc | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/BUILDING.adoc b/BUILDING.adoc
index a30e1329a40..9b25abfa912 100644
--- a/BUILDING.adoc
+++ b/BUILDING.adoc
@@ -172,3 +172,59 @@ CI=true ./mvnw ...
 === Compilation in IntelliJ IDEA fails with `java: plug-in not found: ErrorProne`
 
 Try removing all _"Override compiler parameters per-module"_ entries in _"Settings > Build, Execution, Deployment > Compiler > Java Compiler"_.
+
+[#development-api-compatibility]
+=== Fixing API compatibility check failures
+
+Log4j uses the
+https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-baseline-maven-plugin[BND Baseline Maven Plugin]
+to enforce its
+https://semver.org/[semantic versioning policy].
+Following the
+https://bnd.bndtools.org/chapters/170-versioning.html#best-practices[OSGi versioning best practices], both Log4j artifacts and packages are versioned.
+If you modify Log4j's public API, a BND Baseline error like the following will occur:
+
+[source]
+----
+  Name                        Type     Delta      New    Old    Suggest  If Prov.
+  org.apache.logging.foo      PACKAGE  UNCHANGED  2.1.0  2.1.0  ok       -
+* org.apache.logging.foo.bar  PACKAGE  MINOR      2.3.4  2.3.4  2.4.0    -
+  MINOR        PACKAGE    org.apache.logging.foo.bar
+  ...
+----
+
+The solution of the error depends on the change kind (`Delta`):
+
+[#development-api-compatibility-micro]
+`MICRO`::
++
+For patch level changes modify the `package-info.java` file of the `org.apache.logging.foo.bar` package and update the `@Version` annotation to the number suggested by BND: increment just the patch number.
++
+[source,java]
+----
+@Version("2.3.5")
+package org.apache.logging.foo.bar;
+----
+
+[#development-api-compatibility-minor]
+`MINOR`::
++
+Changes of type `MINOR` require more work:
++
+--
+* Make sure that the current Log4j version is a minor upgrade over the last released version.
+If that is not the case (e.g., it is `2.34.5-SNAPSHOT`) modify the `<revision>` property in the main POM file (e.g., change it to `2.35.0-SNAPSHOT`).
+* Make sure to add a
+https://logging.apache.org/log4j/tools/log4j-changelog.html#changelog-entry-file[changelog entry]
+of type `added`, `changed` or `deprecated` to your PR.
+* As in the
+<<development-api-compatibility-micro,`MICRO` case>>
+modify the `package-info.java` file of the package and update the `@Version` annotation to the **next Log4j version** (`2.35.0` in the example) and **not** the minimal version number suggested by BND.
+The purpose of this policy is to have an alignment between package versions and the last Log4j version, where an API change occurred.
+--
+
+[#development-api-compatibility-major]
+`MAJOR`::
++
+Changes of type `MAJOR` (i.e. breaking changes) are not accepted in the `2.x` branch.
+If you believe it is not a breaking change (e.g., you removed a class **documented** as private), the development team will guide you on how to solve it.