Document API compatibility checks (#3175) (#3858)

This documents the existence of the BND Baseline API compatibility checks and how to fix the generated errors.

Co-authored-by: Piotr P. Karwasz <[email protected]>

Author: jvz

BUILDING.adoc

@@ -144,3 +144,59 @@ Try removing all _"Override compiler parameters per-module"_ entries in _"Settin
 === Compilation in IntelliJ IDEA fails with `java: package org.apache.logging.log4j.plugins.test.validation.plugins does not exist`
 
 We don't know how to fix this.
+
+[#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.