This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new 8abfdfc142 Add versioning and support policy information (#3341)
8abfdfc142 is described below
commit 8abfdfc142f7920471ed4dd0723c4e509a6b9027
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Mon Dec 29 13:08:24 2025 +0100
Add versioning and support policy information (#3341)
This PR introduces a new `versioning` page under *Support* that summarizes
the support status of Apache Log4j releases and documents the long-standing
project policy:
* Log4j follows semantic versioning.
* Only the latest minor of the latest major receives patch releases for bug
and security fixes.
* Vulnerability reports are accepted for **all** `2.x` releases.
* Log4j `1.x` is EOL and no longer accepts vulnerability reports.
Related to #1867
Fixes #3988
Co-authored-by: Volkan Yazıcı <[email protected]>
---
antora-playbook.yaml | 5 +
src/site/antora/modules/ROOT/nav.adoc | 1 +
src/site/antora/modules/ROOT/pages/download.adoc | 299 ++++++++++++++++++++-
src/site/antora/modules/ROOT/pages/versioning.adoc | 144 ++++++++++
4 files changed, 442 insertions(+), 7 deletions(-)
diff --git a/antora-playbook.yaml b/antora-playbook.yaml
index f46037c1a9..babb89756b 100644
--- a/antora-playbook.yaml
+++ b/antora-playbook.yaml
@@ -130,6 +130,11 @@ ui:
.hljs-string {
color: #0f8532;
}
+ /* Colors for maintenance policies */
+ .development { color: #8A4FFF; }
+ .active { color: #28A745; }
+ .eom { color: #FFC107; }
+ .eol { color: #DC3545; }
</style>
- path: partials/header-content.hbs
diff --git a/src/site/antora/modules/ROOT/nav.adoc
b/src/site/antora/modules/ROOT/nav.adoc
index 3fe3771e51..93361ee4c9 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -18,6 +18,7 @@
* xref:download.adoc[Download]
** xref:release-notes.adoc[]
* link:{logging-services-url}/support.html[Support]
+** xref:versioning.adoc[]
** link:{logging-services-url}/security.html[Security]
.xref:manual/index.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/download.adoc
b/src/site/antora/modules/ROOT/pages/download.adoc
index b557ead06b..b320839902 100644
--- a/src/site/antora/modules/ROOT/pages/download.adoc
+++ b/src/site/antora/modules/ROOT/pages/download.adoc
@@ -100,12 +100,297 @@
https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org
Each Log4j artifact is accompanied by a Software Bill of Materials (SBOM).
See {logging-services-url}/download.html#sbom[the Download page of Logging
Services page] for details.
-[#older]
-== Older releases
+[#versions]
+== Available versions
-Are you looking for old versions of Log4j?
-While we recommend always using the latest version, you can find the older
versions here:
+Below you can find the list of available Log4j versions and their associated
maintenance status; Active Development, Active Maintenance, End-of-Maintenance,
and End-of-Life.
+Refer to xref:versioning.adoc[] for details.
-* {logging-services-url}/log4j/1.x/index.html[Log4j 1.x (End of Life, Java
1.4)]
-* {logging-services-url}/log4j/2.3.x/index.html[Log4j 2.3.x (Java 6)]
-* {logging-services-url}/log4j/2.12.x/index.html[Log4j 2.12.x (Java 7)]
+.Maintenance status of selected Log4j versions
+[%header,cols="1h,1,1m,2,2,2,2"]
+|===
+| Version
+| Status
+| Latest release
+| First stable release
+| EOM
+| EOL
+| Notes
+
+| 3.0.x
+| [development]#AD#
+| 3.0.0-beta3
+|
+|
+|
+|
+
+| 2.26.x
+| [development]#AD#
+|
+|
+|
+|
+|
+
+| 2.25.x
+| [active]#AM#
+| 2.25.3
+| 2025-12-15
+|
+|
+|
+
+| 2.24.x
+| [eom]#EOM#
+| 2.24.3
+| 2024-09-03
+| 2025-06-13
+|
+|
+
+| 2.12.x
+| [eom]#EOM#
+| 2.12.4
+| 2019-06-23
+| 2021-12-29
+|
+| Last release supporting Java 7
+
+| 2.3.x
+| [eom]#EOM#
+| 2.3.2
+| 2015-05-09
+| 2021-12-29
+|
+| Last release supporting Java 6
+
+| 1.x
+| [eol]#EOL#
+| 1.2.17
+| 2000-01-08
+| 2014-07-12
+| 2015-08-05
+| Last release supporting Java 1.4
+
+|===
+
+[%collapsible]
+.Click to see all past versions
+====
+
+.Maintenance status of all Log4j versions
+[%header,cols="1h,1,1m,2,2,2"]
+|===
+| Version
+| Status
+| Latest release
+| First release
+| EOM
+| EOL
+
+| 3.0.x
+| [development]#AD#
+| 3.0.0-beta3
+|
+|
+|
+
+| 2.26.x
+| [development]#AD#
+|
+|
+|
+|
+
+| 2.25.x
+| [active]#AM#
+| 2.25.2
+| 2025-06-13
+|
+|
+
+| 2.24.x
+| [eom]#EOM#
+| 2.24.3
+| 2024-09-03
+| 2025-06-13
+|
+
+| 2.23.x
+| [eom]#EOM#
+| 2.23.1
+| 2024-02-17
+| 2024-09-03
+|
+
+| 2.22.x
+| [eom]#EOM#
+| 2.22.1
+| 2023-11-17
+| 2024-02-17
+|
+
+| 2.21.x
+| [eom]#EOM#
+| 2.21.1
+| 2023-10-12
+| 2023-11-17
+|
+
+| 2.20.x
+| [eom]#EOM#
+| 2.20.0
+| 2023-02-17
+| 2023-10-12
+|
+
+| 2.19.x
+| [eom]#EOM#
+| 2.19.0
+| 2022-09-09
+| 2023-02-17
+|
+
+| 2.18.x
+| [eom]#EOM#
+| 2.18.0
+| 2022-06-28
+| 2022-09-09
+|
+
+| 2.17.x
+| [eom]#EOM#
+| 2.17.2
+| 2021-12-17
+| 2022-06-28
+|
+
+| 2.16.x
+| [eom]#EOM#
+| 2.16.0
+| 2021-12-13
+| 2021-12-17
+|
+
+| 2.15.x
+| [eom]#EOM#
+| 2.15.0
+| 2021-12-06
+| 2021-12-13
+|
+
+| 2.14.x
+| [eom]#EOM#
+| 2.14.1
+| 2020-11-06
+| 2021-12-06
+|
+
+| 2.13.x
+| [eom]#EOM#
+| 2.13.3
+| 2019-12-11
+| 2020-11-06
+|
+
+| 2.12.x
+| [eom]#EOM#
+| 2.12.4
+| 2019-06-23
+| 2021-12-29
+|
+
+| 2.11.x
+| [eom]#EOM#
+| 2.11.2
+| 2018-03-11
+| 2019-06-23
+|
+
+| 2.10.x
+| [eom]#EOM#
+| 2.10.0
+| 2017-11-18
+| 2018-03-11
+|
+
+| 2.9.x
+| [eom]#EOM#
+| 2.9.1
+| 2017-08-26
+| 2017-11-18
+|
+
+| 2.8.x
+| [eom]#EOM#
+| 2.8.2
+| 2017-01-21
+| 2017-08-26
+|
+
+| 2.7.x
+| [eom]#EOM#
+| 2.7
+| 2016-10-02
+| 2017-01-21
+|
+
+| 2.6.x
+| [eom]#EOM#
+| 2.6.2
+| 2016-05-25
+| 2016-10-02
+|
+
+| 2.5.x
+| [eom]#EOM#
+| 2.5
+| 2015-12-06
+| 2016-05-25
+|
+
+| 2.4.x
+| [eom]#EOM#
+| 2.4.1
+| 2015-09-20
+| 2015-12-06
+|
+
+| 2.3.x
+| [eom]#EOM#
+| 2.3.2
+| 2015-05-09
+| 2021-12-29
+|
+
+| 2.2.x
+| [eom]#EOM#
+| 2.2
+| 2015-02-22
+| 2015-05-09
+|
+
+| 2.1.x
+| [eom]#EOM#
+| 2.1
+| 2014-10-19
+| 2015-02-22
+|
+
+| 2.0.x
+| [eom]#EOM#
+| 2.0.2
+| 2014-07-12
+| 2014-10-19
+|
+
+| 1.x
+| [eol]#EOL#
+| 1.2.17
+| 2000-01-08
+| 2014-07-12
+| 2015-08-05
+
+|===
+====
diff --git a/src/site/antora/modules/ROOT/pages/versioning.adoc
b/src/site/antora/modules/ROOT/pages/versioning.adoc
new file mode 100644
index 0000000000..a7a1cd92c6
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/versioning.adoc
@@ -0,0 +1,144 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+
+= Versioning and maintenance policy
+
+This page answers the following questions:
+
+- xref:#versioning-policy[How are Log4j releases versioned?]
+- xref:#version-alignment[How shall users align the Log4j API and Log4j Core
versions?]
+- xref:#maintenance-policy[How does Log4j classify maintenance status of
released versions?]
+
+[#versioning-policy]
+== Versioning policy
+
+Since version `2.0`, Log4j follows
+https://semver.org/spec/v2.0.0.html[semantic versioning],
+with release numbers of the form:
+
+[source]
+----
+<major>.<minor>.<patch>[-<pre-release>]
+----
+
+where:
+
+<major>::
++
+The major version number is incremented when **breaking changes** are
introduced.
++
+Upgrading to a new major version typically requires code changes in your
application.
+For each major release, a migration guide is provided.
++
+See xref:migrate-from-log4j1.adoc[] for instructions on migrating from Log4j 1
to Log4j 2.
+
+<minor>::
++
+The minor version number is incremented when new features are added in a
backward-compatible manner, such as:
++
+--
+* New Java methods or classes added to the public API of one of the
+xref:components.adoc[Log4j artifacts].
+* New configuration attributes added to
+xref:manual/plugins.adoc[Log4j Plugins] (appenders, layouts, filters, etc.).
+* Functionality or Java methods/classes being deprecated.
+* Behavioral changes introduced without breaking the public API.
+--
++
+Upgrading to a new minor version usually does not require code changes, unless
you rely on undocumented behavior that has changed.
+To avoid accumulating such changes, we recommend upgrading minor versions
regularly.
++
+When upgrading to a new minor version, review the corresponding
xref:release-notes.adoc[], where behavioral changes are highlighted.
+
+<patch>::
++
+The patch version number is incremented when only backward-compatible bug
fixes are introduced.
++
+Upgrading to a new patch release is the simplest upgrade path.
+
+[%collapsible]
+.Click to see the OSGi package versioning policy
+====
+Since release `2.21.0`, Log4j follows OSGi best practices by versioning each
Java package individually (see
+https://bnd.bndtools.org/chapters/170-versioning.html#versioning-packages[Versioning
Packages]
+for details).
+Package versions are available in the manifest of each artifact and in the
package Javadoc.
+For example, the version of the `org.apache.logging.log4j.core.appender`
package appears in the
+link:javadoc/log4j-core/org/apache/logging/log4j/core/appender/package-summary.html[package
summary page].
+
+Package versions have the form `X.Y.Z`, where the `X.Y` portion corresponds to
the Log4j version that last introduced changes to the package’s public API.
+For example, if a package has version `2.34.5`, then **all** functionality in
that package has been available since Log4j `2.34.0`.
+====
+
+[#version-alignment]
+=== Version alignment
+
+Because
+xref:manual/api.adoc[Log4j API]
+and
+xref:manual/implementation.adoc[Log4j Core implementation]
+are separate artifacts, their versions at **runtime** must be aligned:
+
+* Log4j Core version `X` depends on Log4j API version `X`, so you must have
**at least** version `X` of Log4j API at runtime.
+* Conversely, to use all methods provided by Log4j API version `X`, you need a
Log4j Core version that implements them, i.e., Log4j Core version `X` or later.
+
+The easiest way to ensure version alignment in your project is to use the
+xref:components.adoc#log4j-bom[`log4j-bom` artifact]
+in your build tool.
+Using `log4j-bom` guarantees that compatible versions are selected, regardless
of your tool’s dependency resolution strategy.
+
+[#maintenance-policy]
+== Version lifecycle and maintenance policy
+
+Minor releases of Log4j follow a defined lifecycle consisting of four phases:
+
+[development]#Active development (AD)#::
++
+The version is under active development and may introduce new features.
+Pre-release builds (alpha, beta, etc.) may be published during this phase;
vulnerability reports are accepted and will be addressed.
++
+Versions in this phase are **not recommended** for production use.
+
+[active]#Active maintenance (AM)#::
++
+The version is considered stable and suitable for production.
+In this phase, no new features are accepted: only bug fixes and security fixes.
+Vulnerability reports are accepted and will be addressed.
++
+Due to the limited resources of the Log4j project, **only the latest minor
release of the latest major version** remains in Active Maintenance.
+
+[eom]#End-of-maintenance (EOM)#::
++
+The version is no longer actively maintained. New releases, including security
fixes, are **very unlikely**.
+Vulnerability reports may still be submitted, but fixes will be produced only
in exceptional circumstances.
++
+Because the project is volunteer-driven, any PMC member may choose to create a
release for an EOM version, but such releases should be considered exceptional.
+
+[eol]#End-of-life (EOL)#::
++
+The version is no longer maintained, and **vulnerability reports are not
accepted**.
++
+This final phase is entered after an official PMC vote and public announcement.
+
+[NOTE]
+====
+We avoid using the term *support* to describe the maintenance phases, because
support remains available in **all** phases:
+
+* See {logging-services-url}/support.html#discussions-user[Community support]
for the community-run discussion channels that are offered on a best-effort
basis.
+* Although the ASF does not endorse any third-party commercial providers, some
companies may offer paid support for EOM or EOL versions.
+See {logging-services-url}/support.html#commercial[Commercial support] for a
publicly maintained list of such providers.
+====
