Project release instructions

This section explains how to publish a new release of projects extending from the logging-parent POM and using its reusable CI workflows.

Shared instructions hardcode the following constants:

Project ID

logging-parent

Project version

7.8.0

You must adapt these values for your project! For instance, project ID needs to be replaced with log4j for Log4j, log4j-kotlin for Log4j Kotlin, etc.

Stage the release

  1. Create the release branch:

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

  2. Prepare sources for the release:

    1. Update the revision property in pom.xml

      If your project refers to its own version in the site sources, those need to be updated too. For instance, site-project.version needs to be updated for logging-parent.

    2. Release the changelog:

      ./mvnw -N -P changelog-release

    3. Edit the release notes (i.e., src/changelog/7.8.0/.release-notes.adoc.ftl)

  3. Commit & push your changes:

    git add .
git commit -S -a -m 'Prepare to release `7.8.0`'
git push -u 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.

  4. Verify that the associated GitHub Actions workflow succeeds:

    1. The project.build.outputTimestamp property in pom.xml is updated

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

    3. 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/7.8.0 Subversion repository (along with auxiliary files; website, email texts, etc.)

    4. The release staging website is deployed using the freshly populated release/7.8.0-site-stg-out branch

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

Verify the release

Once the release is staged, the Release Manager should:

  1. Follow the Project release review instructions to verify the integrity of the release.

  2. Some projects have additional integration tests that need to run on the release candidate artifacts:

    logging-log4j2

    Run the integration-test.yaml workflow using the appropriate version number and URL of the Staging Repository as parameters.

Vote the release

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

    Make sure your email is sent in plain text, that is, no HTML! If you are using GMail, 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 the rel/7.8.0 tag (not the release/7.8.0 branch!) 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/7.8.0 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/7.8.0 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/7.8.0
svn commit -m 'Remove `logging-parent` version `7.8.0` files released'

  3. Report the release at reporter.apache.org

In GitHub

  1. Create a new release in GitHub:

    • Use the rel/7.8.0 tag

    • Copy release notes from the generated emails

  2. Close the associated milestone https://github.com/apache/logging-parent/milestones

Publish the release website

  1. Merge the rel/7.8.0 tag (not the release/7.8.0 branch!) to main-site-pro and push it

    git checkout main-site-pro
git rebase origin/main-site-pro    # Sync with the remote repository
git merge rel/7.8.0                # Pull changes up to the newly created tag
git push origin main-site-pro
    If there is no main-site-pro branch yet

    Create it from the rel/7.8.0 tag:

    git checkout -B main-site-pro rel/7.8.0
echo "# $RANDOM" >>.asf.yaml
git commit -S .asf.yaml -m 'Dummy `.asf.yaml` change to trigger the CI'
git push -u origin main-site-pro

  2. Verify that the deploy-site workflow successfully runs the deploy-site-pro job

  3. Verify that the project website is updated

  4. Delete the release staging website branch:

    git push --delete origin release/7.8.0-site-stg-out

Announce the release

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

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