Project release review instructions

Logging Parent provides an extensive CI helper system in the form of reusable GitHub Action workflows. Releases of projects employing these workflows in their CI system can be reviewed using steps shared in this guide.

Release verification

Releases of projects employing the Logging Parent CI helper system can be verified with following steps:

  1. Check out the release distribution:

    svn co https://dist.apache.org/repos/dist/dev/logging/<projectName>/<releaseVersion> \
  <projectName>-<releaseVersion> && cd $_
    Click to see how to check out using wget instead of svn 
    mkdir <projectName>-<releaseVersion> && cd $_
wget --cut-dirs=6 \
     --no-host-directories \
     --no-parent \
     --recursive \
     https://dist.apache.org/repos/dist/dev/logging/<projectName>/<releaseVersion>/

  2. Verify checksums:

    • Linux/macOS

    • Windows

    sha512sum --check *.sha512
    certUtil -hashfile <FILE> SHA512

  3. Import the release manager GPG keys, unless you haven’t earlier done so:

    wget -O - https://downloads.apache.org/logging/KEYS | gpg --import

  4. Verify signatures:

    for sigFile in *.asc; do gpg --verify $sigFile ${sigFile%.asc}; done

  5. Extract sources:

    umask 0022
unzip -q *-src.zip -d src
cd src

  6. Verify the build:

    • Linux/macOS

    • Windows

    sh mvnw verify \
  -Prelease artifact:compare \ (1)
  -Dreference.repo=https://repository.apache.org/... (2)
    1 artifact:compare goal, along with -Prelease instruction, is used to verify the build reproducibility. That is, to verify that the artifacts generated by CI match the ones you locally generate.
    2 Place here the Nexus repository URL shared in the release vote email 
    sh mvnw verify

    If the reviewed project happen to have Docker-based tests (e.g., Log4j), you can enable these tests by activating the docker Maven profile using the -Pdocker option.

Troubleshooting

If you happen to experience problems while trying to follow the verification steps, unless there is a bug in the workflows, it is most likely due to an unexpected setup in your build host. You can use one of the techniques below to troubleshoot such problems:

Clean up the local Maven repository
rm -rf ~/.m2/repository
Rerun failing tests
sh mvnw install -DskipTests
sh mvnw test \
  -Dsurefire.rerunFailingTestsCount=3 \
  -pl <failingModule> -Dtest=<failingTestClassName>
Use a Java runtime matching the one in CI

Logging Parent uses Azul Zulu builds of OpenJDK in reusable GitHub Action workflows. You can try building with Azul Zulu.

Use a Docker container for the build

You can use a Docker container to build the sources as follows:

  1. Run the container with project sources and a Maven home mounted:

    export DOCKER_IMAGE="azul/zulu-openjdk:17" (1)
docker pull $DOCKER_IMAGE
docker run -it --rm \
  --network host \
  -v $PWD/src:/src \ (2)
  -v $PWD/m2:/root/.m2 \ (3)
  $DOCKER_IMAGE \
  /bin/bash
    1 The tag (i.e., 17) denotes the Java version and should match the one used by the project you’re trying to verify
    2 Mount the project sources
    3 Mount a local Maven home to avoid repetitive Maven downloads when you start container multiple times

  2. Build the sources:

    apt update && apt install -y libcurl4 (1)
cd /src
sh mvnw install -DskipTests (2)
    1 Required only for Log4j builds, which need libcurl4 for MongoDB tests
    2 Only installing first to allow re-running tests, if needed

  3. Verify the build:

    sh mvnw verify \
  -Prelease artifact:compare \ (1)
  -Dreference.repo=https://repository.apache.org/... (2)
    1 artifact:compare goal, along with -Prelease instruction, is used to verify the build reproducibility. That is, to verify that the artifacts generated by CI match the ones you locally generate.
    2 Place here the Nexus repository URL shared in the release vote email