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

Create the release branch:

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

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)
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.
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 necessary fixes, push, and repeat.
Close the repository in repository.apache.org using a self-explanatory description, e.g., `logging-parent` version `7.8.0` RC1

Vote the release

Send the vote email uploaded to the dist.apache.org/repos/dist/dev/logging/logging-parent/7.8.0 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, enable the "Plain text mode" while composing your message.

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

Pull the most recent changes and tags
```
git fetch -p
```
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.

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

Set the revision property to the next development version (e.g., 7.9.0-SNAPSHOT) in pom.xml
Commit changes and push the main branch

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

Release the repository in repository.apache.org

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

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
delete the folder from an earlier release in release/logging/logging-parent
commit your changes in release/logging/logging-parent
delete the dev/logging/logging-parent/7.8.0 folder (stash the generated announcement email somewhere, you will need it later on)
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'

Report the release at reporter.apache.org

In GitHub

Create a new release in GitHub:
- Use the rel/7.8.0 tag
- Copy release notes from the generated emails
Close the associated milestone https://github.com/apache/logging-parent/milestones

Publish the release website

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

Verify that the deploy-site workflow successfully runs the deploy-site-pro job
Verify that the project website is updated

Delete the release staging website branch:

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

Announce the release

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.