This is an automated email from the ASF dual-hosted git repository.
mattsicker pushed a commit to branch doc/3.x/port-3175
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit d48b1408da02d7033cd9a27fd69368ba4e582e88
Author: Piotr P. Karwasz <piotr.git...@karwasz.org>
AuthorDate: Tue Nov 5 11:34:47 2024 +0100
Document API compatibility checks (#3175)
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 8aec9b3ed3..159322b8d8 100644
--- a/BUILDING.adoc
+++ b/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.
