Logging Parent is the parent project internally used in Maven-based projects of the Apache Logging Services.

Features

Logging Parent aims to deliver the following features.

Parent POM

The provided parent POM features the following conveniences:

CycloneDX Software Bill of Materials (SBOM)

Logging Parent streamlines the generation of CycloneDX Software Bill of Materials (SBOM) using cyclonedx-maven-plugin. Plugin execution is configured and activated to generate SBOM files for each module, including the root one. Generated SBOM files are attached as artifacts with cyclonedx classifier and XML extensions, that is, <artifactId>-<version>-cyclonedx.xml.

Produced SBOMs are enriched with vulnerability-assertion references to a CycloneDX Vulnerability Disclosure Report (VDR) that Apache Logging Services uses for all projects it maintains. This VDR is accessible through the following URL: https://logging.apache.org/cyclonedx/vdr.xml

Reusable GitHub Actions workflows

The provided reusable GitHub Actions workflows feature the following conveniences:

build-reusable.yaml

  • Compiles against Java 8 bytecode using the specified Java compiler version

  • Verifies reproducibility

  • Automatically merges verified dependabot PRs

deploy-snapshot-reusable.yaml

  • Deploys SNAPSHOT artifacts

deploy-release-reusable.yaml

  • Deploys release artifacts

  • Updates revision and project.build.outputTimestamp Maven properties

  • Generates the release notes

  • Generates the distribution ZIP containing Git-tracked sources, release notes, binary attachments, NOTICE.txt, etc.

  • Generates the release vote & announcement emails

  • Uploads the distribution ZIP and emails to SVN

Usage

You can use Logging Parent as follows:

  1. Add org.apache.logging:logging-parent:10.4.0 as a parent to your pom.xml

    1. Check if ./mvnw verify succeeds, otherwise make necessary changes

  2. Copy and adapt the support files (.gitignore, .github/workflows/build.yaml, etc.)

  3. Check out your website:

    ./mvnw site
python -m http.server -d target/site

Development

Logging Parent uses GitHub for source code management.

The project requires a Java compiler matching the [17,18) range and targets Java 8.

You can build and verify sources using:

./mvnw verify

You can build and view the website as follows:

./mvnw site
python -m http.server -d target/site

Distribution

In accordance with the Apache Software Foundation’s release distribution policy and creation process, project artifacts are officially accessible from the following locations:

See the release instructions for details.

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 the Log4j support policy for details.

Security

If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to the Log4j security mailing list. See the Log4j Security page for further details.

Release Notes

10.4.0

Release date

2023-11-13

This minor release contains several small improvements.

Added

  • Add deterministic Palantir Java formatter

Changed

  • Increase directory scanning depth from 8 to 32 in the distribution BeanShell script

10.3.0

Release date

2023-11-09

This minor release contains several small improvements.

Added

  • Add support to extend the bnd-maven-plugin configuration with bnd-extra-config property (apache/logging-log4j2#1895)

  • Add support to replace project.build.outputTimestamp Maven property in CI (50)

  • Add XSLT transformation step to add a deterministic serialNumber and VDR links to the SBOM

  • Add support for an optional spotbugs-exclude.xml file

Changed

  • deploy-release-reusable.yaml is improved to automatically derive deployed artifacts as attachments. This renders both distribution-attachment-filepath-pattern and distribution-attachment-count input arguments redundant for almost all cases.

  • Disable the usage of <distributionManagement> and alpha releases in the bnd-baseline-maven-plugin

  • Convert bnd-maven-plugin API leakage warnings to errors (apache/logging-log4j2#1895)

  • Update com.github.spotbugs:spotbugs-annotations to version 4.8.1 (58)

  • Update com.github.spotbugs:spotbugs-maven-plugin to version 4.8.1.0 (57)

  • Update com.google.errorprone:error_prone_core to version 2.23.0 (49)

  • Update org.apache.maven.plugins:maven-artifact-plugin to version 3.5.0

  • Update org.cyclonedx:cyclonedx-maven-plugin to version 2.7.10 (54)

Fixed

  • Fix broken changelog entry validation

  • Attach flatten:clean to clean phase

  • Add missing Implementation- and Specification- entries in MANIFEST.MF to bnd-maven-plugin configuration (apache/logging-log4j2#1923)

10.2.0

Release date

2023-10-18

This minor release contains several small improvements.

Added

  • Added support for auto-generating CycloneDX Software Bill of Materials (SBOM)

Changed

  • Add a compulsory bnd-baseline-maven-plugin execution to check for breaking API changes

  • Apply the default bnd-maven-plugin configuration to all the plugin’s goals

  • Moves .flattened-pom.xml to the same directory as pom.xml to preserve the relative parent path. This requires adding .flattened-pom.xml to the .gitignore file of the repository.

  • Update org.apache.logging.log4j:log4j-changelog-maven-plugin to version 0.5.0

  • Update log4j-changelog XSD (used for validating changelog entries) to version 0.1.2

  • Update com.github.spotbugs:spotbugs-annotations to version 4.8.0 (44)

Fixed

  • Prioritize definitions in bnd-extra-* variables over those inherited (39)

  • Keep parent in flatten-bom configuration (37)

  • Remove build in flatten-bom configuration

  • Fixed the archiving of symbolically linked directories in the distribution Maven profile (43)

  • Used specific execution IDs in defaultGoals to avoid running unwanted plugins

10.1.1

Release date

2023-10-02

This patch release contains minor fixes addressing issues blocking the release of log4j-tools, log4j-kotlin, etc.

Added

  • Used project.build.outputTimestamp to timestamp generated distribution files

Changed

  • Changes the default OSGi and module name to use full stops . instead of non-alphanumeric characters

  • Update com.diffplug.spotless:spotless-maven-plugin to version 2.40.0

Fixed

  • Fixed checksum (i.e., *.sha512) file format

  • Fix BND module name detection on multi-release JARs

10.1.0

Release date

2023-09-28

This minor release focuses on shipping AsciiDoc-based website generation convenience targeting the src/site folder. As a part of this effort, logging-parent started publishing its own website and log4j-changelog support is switched from Markdown to AsciiDoc.

The introduced bnd-maven-plugin default auto-generates both OSGi and JPMS descriptors. Users only need to annotate packages that are to be exported with org.osgi.annotation.bundle.Export, plugin will do the rest of the magic. Hence, no need for custom .bnd and/or module-info.java files anymore. In particular, we expect the absence of module-info.java files to avoid several IDE and testing related headaches.

Added

  • Added asciidoc and constants-tmpl-adoc profiles to generate AsciiDoc-based websites from src/site

  • Added support to auto-generate changelog entries for dependabot updates

  • Added bnd-maven-plugin defaults to auto-generate both OSGi and JPMS descriptors

  • Added CI report uploading in case of test or reproducibility failures (28)

  • Started publishing the project website

Changed

  • Switched the default log4j-changelog configuration from Markdown (.release-notes.md.ftl and .index.md.ftl) to AsciiDoc (.release-notes.adoc.ftl and .index.adoc.ftl)

  • Update actions/checkout to version 4.1.0

  • Update com.github.spotbugs:spotbugs-maven-plugin to version 4.7.3.6

  • Update com.google.errorprone:error_prone_core to version 2.22.0

  • Update org.apache:apache to version 30

  • Update org.osgi:osgi.annotation to version 8.1.0

Removed

  • Removed project.build.outputTimestamp override since it is already provided by the parent POM and its old value 0 was causing reproducibility issues for spring-boot:repackage

Fixed

  • Replaced incorrect java.version Maven property override with maven.compiler.{source,release,target}

10.0.0

Release date

2023-09-08

This minor release contains various improvements that we expect to relieve the load on pom.xml and GitHub Actions workflows of Maven-based projects we parent. This is of particular importance while managing and cutting releases from multiple repositories. See README.adoc for the complete list of features and their usage.

See this log4j-tools GitHub Actions workflow run demonstrating a successful release cut using a SNAPSHOT version of this logging-parent release. All preparations (release notes, source and binary distributions, vote & announcement emails, etc.) are staged to both Nexus and SVN and waiting the release manager to proceed.

Added

  • Added changelog-export profile to easily export changelogs to Markdown files

  • Added changelog-release profile to easily move src/changelog/.?.x.x contents to their associated release directory

  • Added deploy profile to ease the Maven deploy goal

  • Added asciidoc profile to easily create a distribution file containing Git-tracked sources, release notes, binary attachments, NOTICE.txt, etc.

  • Documented release instructions (i.e., RELEASING.md)

  • Added release profile to share common release-specific Maven configuration

  • Added reusable GitHub Actions workflows to share CI boilerplate for other repositories

  • Switched to using log4j-changelog-maven-plugin for managing changelog and release notes

Changed

  • Switched to semantic versioning (old version: 9, new version: 10.0.0)

Release instructions

In the code examples below, assuming the version to be released is 7.8.0.

The website-specific instructions are only applicable to projects which employ the reusable CI workflow with site-enabled input set to true.

Stage the release

  1. Create and push the release branch:

    git fetch -p
git checkout -B release/7.8.0 origin/main
git push origin release/7.8.0

    release/-prefixed branches trigger a particular GitHub Actions workflow and its run is idempotent. You can iterate on the release/7.8.0 branch to perfect it.

  2. Verify that the associated GitHub Actions workflow succeeds:

    1. revision property in pom.xml is updated

    2. Changelog is released (i.e., src/changelog/7.8.0 folder is populated)

    3. Signed artifacts are uploaded to the Staging Repositories in repository.apache.org

    4. Signed distribution and its checksum (e.g., apache-logging-parent-7.8.0-{bin,src}.{zip,.zip.asc,.zip.sha512}) are uploaded to dist.apache.org/repos/dist/dev/logging/logging-parent Subversion repository (along with auxiliary files; website, email texts, etc.)

    If not, commit necessary fixes, push, and repeat.

  3. Close the repository in repository.apache.org

Stage the release website

  1. Checkout the asf-staging branch of the website repository

  2. Override the contents of the 7.x folder using the website uploaded to the dist.apache.org/repos/dist/dev/logging/logging-parent Subversion repository

These steps can be summarized as follows in shell:

# Clone repositories (unless you already have them!)
svn co https://dist.apache.org/repos/dist/dev/logging logging-dist-dev
git clone https://github.com/apache/logging-parent logging-parent

# Checkout the branch
cd logging-parent
git checkout -B asf-staging origin/asf-staging

# Override the website
git rm -rf 7.x
mkdir 7.x
unzip ../logging-dist-dev/logging-parent/*-7.8.0-site.zip -d 7.x
git add 7.x
git commit -a -m 'Add `logging-parent` version `7.8.0` website'
git push origin asf-staging

Changes should be visible in the project staging website.

Vote the release

  1. Send the vote email uploaded to the dist.apache.org/repos/dist/dev/logging/logging-parent Subversion repository

    Fix the cited repository.apache.org URL in the generated email! It changes after every Nexus deployment.

    Make sure your email is sent in plain text, that is, no HTML! If you are using GMail, simply enable the "Plain text mode" while composing your message.

  2. Once the consensus is reached within the set time frame, respond to the first post in the thread as follows:

    Adding my +1.

With that, the release passes with 3 binding +1 votes from <PMC-member-1>, ..., <PMC-member-N>, and me. I will continue the release process.

Publish the release

In the git repository

  1. Pull the most recent changes and tags

    git fetch -p

  2. Tag the release (e.g., rel/7.8.0) and push it

    git tag -a rel/7.8.0 <COMMIT-ID> -m 7.8.0     (1)
git push origin rel/7.8.0
    1 You can find the COMMIT-ID in the generated vote email.

    The ASF infrastructure treats rel/-prefixed git tags special and ensures they are immutable for provenance reasons.

  3. Merge release/7.8.0 to main

    git checkout main
git rebase origin/main    # Sync with the remote repository
git merge rel/7.8.0       # Pull changes up to the newly created tag

  4. Set the revision property to the next development version (e.g., 7.9.0-SNAPSHOT) in pom.xml

  5. Commit changes and push the main branch

  6. Delete the local and remote copies of the release/7.8.0 branch

    git branch -D release/7.8.0
git push --delete origin release/7.8.0

In the ASF infrastructure

  1. Release the repository in repository.apache.org

  2. In dist.apache.org/repos/dist Subversion repository,

    1. create the release/logging/logging-parent/7.8.0 folder, and copy the signed sources and their checksum from dev/logging/logging-parent to there

    2. delete the folder from an earlier release in release/logging/logging-parent

    3. commit your changes in release/logging/logging-parent

    4. delete the dev/logging/logging-parent folder (stash the generated announcement email somewhere, you will need it later on)

    5. commit changes your changes in dev/logging/logging-parent

    These steps can be summarized as follows in shell:

    # Clone repositories (unless you already have them!)
svn co https://dist.apache.org/repos/dist/dev/logging logging-dist-dev
svn co https://dist.apache.org/repos/dist/release/logging logging-dist-rel

# Update `release` folder
cd logging-dist-rel
mkdir -p logging-parent/7.8.0
cp ../logging-dist-dev/logging-parent/*-7.8.0-{bin,src}.* logging-parent/7.8.0/
svn add logging-parent/7.8.0
svn commit -m 'Add `logging-parent` version `7.8.0` distribution'

# Update `dev` folder
cd ../logging-dist-dev
cp logging-parent/*-7.8.0-email-announce.txt /tmp
svn rm logging-parent
svn commit -m 'Remove `logging-parent` version `7.8.0` files released'

  3. Report the release at reporter.apache.org

In GitHub

Create a new release in GitHub

  1. Use the rel/7.8.0 tag

  2. Copy release notes from the generated emails

Publish the release website

  1. Checkout the asf-site branch of the website repository

  2. Replace the 7.x folder with the one in asf-staging branch

These steps can be summarized as follows in shell:

# Clone the repository (unless you already have it!)
git clone https://github.com/apache/logging-parent logging-parent

# Checkout the branch
cd logging-parent
git checkout -B asf-site origin/asf-site

# Override the website
git rm -rf 7.x
mkdir 7.x
git checkout origin/asf-staging -- 7.x
git add 7.x
git commit -a -m 'Add `logging-parent` version `7.8.0` website'
git push origin asf-site

Changes should be visible in the project website.

Announce the release

  1. Send the announcement email uploaded to the dist.apache.org/repos/dist/dev/logging/logging-parent Subversion repository

    Make sure your email is sent in plain text, that is, no HTML! If you are using GMail, simply enable the "Plain text mode" while composing your message.

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.