src/site/index.adoc

////
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

    https://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.
////

include::_constants.adoc[]
:freemarker-link: https://freemarker.apache.org[FreeMarker]

= Log4j Tools

Tooling **internally** used by https://logging.apache.org/log4j/2.x/[the Apache Log4j project] infrastructure.

include::_log4j-changelog.adoc[]

include::_log4j-changelog-maven-plugin.adoc[]

[#development]
== Development

{project-name} uses {project-github-url}[GitHub] for source code management.

The project requires a Java compiler matching the `{java-compiler-version}` range and targets Java `{java-target-version}`.

You can build and verify sources using:

[source,bash]
----
./mvnw verify
----

You can build and view the website as follows:

[source,bash]
----
./mvnw -N site
python -m http.server -d target/site
----

[#distribution]
== Distribution

In accordance with the Apache Software Foundation's release https://infra.apache.org/release-distribution.html[distribution policy] and https://infra.apache.org/release-publishing.html[creation process], project artifacts are _officially_ accessible from the following locations:

* ASF https://repository.apache.org/content/repositories/releases[Release] and https://repository.apache.org/content/repositories/snapshots[snapshot] repositories (mirrored to https://central.sonatype.dev/[the Maven Central Repository])
* ASF https://downloads.apache.org/logging/{project-id}[Distribution directory]

See xref:#release-instructions[the release instructions] for details.

[#maven-bom]
=== Maven Bill of Materials (BOM)

To keep your {project-name} module versions aligned, a https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms[Maven Bill of Materials (BOM) POM] is provided for your convenience.

To use this with Maven, add the dependency listed below to your `pom.xml` file.
Note that the `<dependencyManagement>` nesting and the `<scope>import</scope>` instruction.
This will _import_ all modules bundled with the associated Log4j release to your `dependencyManagement`.
As a result, you don't have to specify versions of the imported modules (`log4j-changelog`, etc.) while using them as a `<dependency>`.

.`pom.xml` snippet importing `log4j-tools-bom`
[source,subs="+attributes"]
----
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-tools-bom</artifactId>
      <version>{project-version}</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>
----

[#cyclonedx-sbom]
=== CycloneDX Software Bill of Materials (SBOM)

Starting with version `0.6.0`, {project-name} distributes https://cyclonedx.org/capabilities/sbom/[CyclenoDX Software Bill of Materials (SBOM)] along with each deployed artifact.
This is streamlined by `logging-parent`, see https://logging.apache.org/logging-parent/latest/#cyclonedx-sbom[its website] for details.

[#support]
== Support

Please keep in mind that this project is intended for internal usage only.
You can use GitHub Issues for feature requests and bug reports – not questions!
See https://logging.apache.org/log4j/2.x/support.html[the Log4j support policy] for details.

[#security]
== Security

If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to mailto:security@logging.apache.org[the Log4j security mailing list].
See https://logging.apache.org/log4j/2.x/security.html[the Log4j Security page] for further details.

include::_release-notes.adoc[]

[#release-instructions]
== Release instructions

{project-name} employs the CI/CD foundation provided by the https://logging.apache.org/logging-parent[`logging-parent`].
You can simply use its release instructions.

[#license]
== License

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
See `NOTICE.txt` 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 https://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.