Add versioning and support policy information

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

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[]

src/site/antora/modules/ROOT/pages/download.adoc

@@ -100,12 +100,6 @@ 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
+include::partial$supported-versions.adoc[leveloffset=+1]
 
-Are you looking for old versions of Log4j?
-While we recommend always using the latest version, you can find the older versions here:
-
-* {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)]
+See xref:versioning.adoc[Version lifecycle and maintenance policy] for more information about the maintenance lifecycle of Log4j versions.

src/site/antora/modules/ROOT/pages/versioning.adoc

@@ -0,0 +1,180 @@
+////
+    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 support policy
+
+include::partial$supported-versions.adoc[leveloffset=+1]
+
+
+[#versioning-policy]
+== Versioning policy
+
+Since version 2.0, Apache 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[]:
+behavioral changes are highlighted in the release description and listed in the “Changed” section.
+
+<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.
++
+[NOTE]
+====
+The classification of a behavioral change as a minor or patch release may vary by interpretation:
+what is considered a bug by one user may be viewed as a feature by another.
+====
+
+[%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 Apache 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 X, you need a Log4j Core version that implements them, i.e., Log4j Core 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 Apache Log4j follow a defined lifecycle consisting of four phases:
+
+[development]#Active development#::
++
+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#::
++
+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 Apache 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.
+
+[cols="3h,1,1,1"]
+|===
+| Maintenance phase | New features | Security/bug fixes | Security advisories
+
+| [development]#Active development#
+| **Yes**
+| **Yes**
+| **Yes**
+
+| [active]#Active maintenance#
+| No
+| **Yes**
+| **Yes**
+
+| [eom]#End-of-maintenance (EOM)#
+| No
+| No
+| **Yes**
+
+| [eol]#End-of-life (EOL)#
+| No
+| No
+| No
+
+|===
+
+[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.
+====