diff --git a/antora-playbook.yaml b/antora-playbook.yaml index f46037c1a9f..babb89756b4 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; } - path: partials/header-content.hbs diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index 3fe3771e513..93361ee4c91 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 b557ead06b8..b320839902c 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 00000000000..a7a1cd92c67 --- /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] +---- +..[-] +---- + +where: + +:: ++ +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. + +:: ++ +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. + +:: ++ +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. +====