Skip to content

Commit

Permalink
Provide guidelines and templates for the release process (#413)
Browse files Browse the repository at this point in the history
  • Loading branch information
swebb2066 authored Oct 11, 2024
1 parent 1370eee commit 6583772
Show file tree
Hide file tree
Showing 7 changed files with 285 additions and 0 deletions.
18 changes: 18 additions & 0 deletions admin/MailTemplate.Announce.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
To: [email protected], [email protected]
Subject: [ANNOUNCE] Apache log4cxx 1.3.0 released

Hi,

The Apache log4cxx team is pleased to announce the 1.3.0 release.

For the list of new features and issues corrected, see:
https://logging.apache.org/log4cxx/1.3.0/changelog.html#rel_1_3_0

For official release downloads, see:
https://logging.apache.org/log4cxx/1.3.0/download.html

For instructions on building Log4cxx, see:
https://logging.apache.org/log4cxx/1.3.0/build.html

All other information is available on the Log4cxx project website:
https://logging.apache.org/log4cxx/1.3.0
14 changes: 14 additions & 0 deletions admin/MailTemplate.Result.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
To: [email protected]
Subject: [RESULT][VOTE] Release Apache Log4cxx 1.3.0

and here is my +1.

With that the vote passed with 3 +1 votes from ... and myself.
I will continue the release process.

Stephen

---------------------------------------------------------------------------------------------------
This is a vote to release the Apache Log4cxx 1.3.0.

...
20 changes: 20 additions & 0 deletions admin/MailTemplate.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
To: [email protected]
Subject: [VOTE] Release Apache Log4cxx 1.3.0

This is a vote to release the Apache Log4cxx 1.3.0.

Website: https://logging.staged.apache.org/log4cxx/1.3.0/changelog.html
GitHub: https://github.com/apache/logging-log4cxx
Commit: <todo insert>
Distribution: https://dist.apache.org/repos/dist/dev/logging/log4cxx/
Signing key: C6FC425C96722EFC4E2D02D5D4305EBC16B4A78D
Review kit: https://github.com/apache/logging-log4cxx/admin/release-review-instructions.md

Please download, test, and cast your votes on this mailing list.

[ ] +1, release the artifacts
[ ] -1, don't release, because ...

This vote is open for 72 hours and will pass unless getting a net negative vote count.
All votes are welcome and we encourage everyone to test the release, but only the
Logging Services PMC votes are officially counted.
39 changes: 39 additions & 0 deletions admin/release-review-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
Reviewing a Log4cxx release
===================

The review should confirm the uploaded source code is not corrupt and
is identical to the package generated by the Github action.
The steps below use version 1.3.0 as an example.

Prerequisites
----------

* [GNU Privacy Guard](https://www.gnupg.org/) is installed on your system
* A C++ compiler is available on your system
* cmake, APR and APR-Util are installed on your system
* You have imported the [Apache Logging KEYS file](https://dist.apache.org/repos/dist/release/logging/KEYS)

Steps
-----

1. Download, verify check-sums, verify signatures, build and test
- Save to your system the verification script https://github.com/apache/logging-log4cxx/validate-release.sh
- Run the script
- For success, the final output line needs to include:
- `100% tests passed, 0 tests failed out of 62`
1. Download the packaged release files from Github
- Open https://github.com/apache/logging-log4cxx/commits/v1.3.0-RC1 in your web browser
- Click the green tick mark on the top commit
- The `All checks have passed` pop-up window will display
- Click the "Details" link on the row next to `Generate release files / Package code for release`
- The `Package for release` log window will display
- Click the `>` to the left of `Run action/upload-artifact`
- The numbered steps will display
- Click the link next to `Artifact download URL:`
- The browser will download the file `Upload release files.zip` onto your system
1. Confirm the artifacts were sourced from Github using these commands
- `mkdir /tmp/log4cxx-github`
- `cd /tmp/log4cxx-github`
- `unzip "$HOME/Downloads/Upload release files.zip"`
- `diff /tmp/log4cxx{,-github}/apache-log4cxx-1.3.0.tar.gz.sha512`
- `diff /tmp/log4cxx{,-github}/apache-log4cxx-1.3.0.zip.sha512`
75 changes: 75 additions & 0 deletions admin/releasing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
Releasing a Log4cxx version
===================

This document lists the steps that must be performed to release Log4cxx
using 1.3.0 as the example.

Prerequisites
----------

* The version number (in src/cmake/projectVersionDetails.cmake) has been updated
* The change log (in src/site/markdown/change-report-gh.md) is up-to-date.
* The web-site for the new version has been published to https://logging.staged.apache.org/log4cxx (using [this procedure](staging.md) )
* An e-mail has been sent to [email protected] announcing the intention to release
* Your public key is available in [Apache Logging KEYS file](https://dist.apache.org/repos/dist/release/logging/KEYS)

Steps
-----

1. Tag HEAD as the release candidate
- `git checkout master`
- `git push origin tag v1.3.0-RC1`
1. Remove the old artifacts from svn
- `svn co https://dist.apache.org/repos/dist/dev/logging -N apache-dist-logging-dev`
- `cd apache-dist-logging-dev`
- `svn up log4cxx`
- `cd log4cxx`
- `svn delete *`
1. Download the packaged release files from Github
- Open https://github.com/apache/logging-log4cxx/commits/v1.3.0-RC1 in your web browser
- Click the green tick mark on the top commit
- The `All checks have passed` pop-up window will display
- Click the "Details" link on the row next to `Generate release files / Package code for release`
- The `Package for release` log window will display
- Click the `>` to the left of `Run action/upload-artifact`
- The numbered steps will display
- Click the link next to `Artifact download URL:`
- The browser will download the file `Upload release files.zip` onto your system
1. Unpack the release files using these commands
- `cd apache-dist-logging-dev/log4cxx`
- `unzip "$HOME/Downloads/Upload release files.zip"`
1. Sign release artifacts (Refer: https://infra.apache.org/release-signing.html) (with `apache-dist-logging-dev/log4cxx` as the working directory)
- `gpg --armor --output apache-log4cxx-1.3.0.zip.asc --detach-sig apache-log4cxx-1.3.0.zip`
- `gpg --armor --output apache-log4cxx-1.3.0.tar.gz.asc --detach-sig apache-log4cxx-1.3.0.tar.gz`
1. Send the new artifacts to svn (with `apache-dist-logging-dev/log4cxx` as the working directory)
- `svn add *`
- `svn commit -m 'log4cxx 1.3.0'`
- check https://dist.apache.org/repos/dist/dev/logging/log4cxx
1. Raise a vote on the mailing list ([email protected])
- Using [this template](MailTemplate.txt)
1. Wait 72 hours (the minimum)
1. When the vote has 3 or more +1's, announce the result
- Using [this template](MailTemplate.Result.txt)
1. Get artifacts up to https://downloads.apache.org/logging/log4cxx/
- `svn move -m "Release log4cxx 1.3.0" https://dist.apache.org/repos/dist/dev/logging/log4cxx https://dist.apache.org/repos/dist/release/logging/log4cxx/1.3.0`
1. Tag the released version
- `git checkout v1.3.0-RC1`
- `git push origin tag rel/v1.3.0`
1. Enter the release date in `src/site/markdown/change-report-gh.md`
- Commit the change
- Update the staged web site using [the update procedure](staging.md)
1. Check the staged web site is ready to go live
- Are you are seeing the release date on changelog?
- Do the links on download page work?
1. Make the new version of the web site live.
- `git clone https://github.com/apache/logging-log4cxx-site /tmp/log4cxx-site`
- `cd /tmp/log4cxx-site`
- `git checkout asf-site`
- `git rebase asf-staging`
- `git push origin asf-site`
1. Check https://logging.apache.org/log4cxx (after a minute or two)
- Are you seeing the new pages?
- Do the download links now work?
1. Announce the release to the mailing lists ([email protected], [email protected])
- Using [this template](MailTemplate.Announce.txt)

66 changes: 66 additions & 0 deletions admin/staging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
Updating the Log4cxx web site
===================

This document describes the steps used to update Log4cxx web site
using 1.3.0 as an example Log4cxx version.

Prerequisites
----------

* The documentation changes have been committed to the log4cxx source code repository
* Doxygen 1.9.6 in available on your system
* APR and APR-Util are available on your system

Steps to update the Log4cxx web site
-----

1. Use Doxygen to generate the HTML, PNG, JS and CSS files
- `git clone https://github.com/apache/logging-log4cxx /tmp/log4cxx`
- `cmake -B /tmp/build -S /tmp/log4cxx -DBUILD_SITE=on`
- `cmake --build /tmp/build -t doc_doxygen`
1. Check out the `asf-staging` branch of `logging-log4cxx-site`
- `git clone https://github.com/apache/logging-log4cxx-site /tmp/log4cxx-site`
- `cd /tmp/log4cxx-site`
- `git checkout asf-staging`
1. Use the newly generated files for the web site documentation
- `git rm -r 1.3.0`
- `mv /tmp/build/src/site/html 1.3.0`
- `git add 1.3.0`
1. Push the `asf-staging` branch to Github and wait a bit
- `git commit -m "Improved the ... documentation"`
- `git push`
1. Check https://logging.staged.apache.org/log4cxx (after a minute or two)
- are you seeing the correct releases page?


Steps to add a new version to the Log4cxx web site
-----

1. Use Doxygen to generate the HTML, PNG, JS and CSS files
- `git clone https://github.com/apache/logging-log4cxx /tmp/log4cxx`
- `cmake -B /tmp/build -S /tmp/log4cxx -DBUILD_SITE=on`
- `cmake --build /tmp/build -t doc_doxygen`
1. Check out the `asf-staging` branch of `logging-log4cxx-site`
- `git clone https://github.com/apache/logging-log4cxx-site /tmp/log4cxx-site`
- `cd /tmp/log4cxx-site`
- `git checkout asf-staging`
1. Use the newly generated files for the web site documentation
- `git rm -r 1.3.0`
- `mv /tmp/build/src/site/html /tmp/log4cxx-site/1.3.0`
- `git add 1.3.0`
1. Update the symbolic links in the base of the web site working directory
- `cd /tmp/log4cxx-site`
- `rm latest_stable old_stable`
- `ln -s 1.3.0 latest_stable`
- `ln -s 1.2.0 old_stable`
- `git add latest_stable old_stable`
1. Update `.htaccess` so the final `RewriteRule` redirects to the new version
- `RewriteRule ^(.*)$ /log4cxx/1.3.0/$1 [R=temp,L]`
- `git add .htaccess`
1. Push the `asf-staging` branch to github and wait a bit
- `git commit -m "Add the 1.3.0 documentation"`
- `git push`
1. Check https://logging.staged.apache.org/log4cxx (after a minute or two)
- Are you seeing the new pages?
- Download links for the new version should (at this point) not work

53 changes: 53 additions & 0 deletions admin/validate-release.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/bin/sh

set -e

VERSION=$1
if [ -z "$VERSION" ] ; then
VERSION=1.3.0
fi

if [ -z "$BASE_DL" ] ; then
BASE_DL=https://dist.apache.org/repos/dist/dev/logging/log4cxx
fi
if [ -z "$ARCHIVE" ] ; then
ARCHIVE=apache-log4cxx-$VERSION
fi
if [ -z "$TEST_DIRECTORY" ] ; then
TEST_DIRECTORY=/tmp/log4cxx
fi

test -d "$TEST_DIRECTORY" || mkdir "$TEST_DIRECTORY"
cd "$TEST_DIRECTORY"

FULL_DL="$BASE_DL/$ARCHIVE"

for EXT in "tar.gz" "zip" ; do
wget "$FULL_DL.$EXT" || exit $?
wget "$FULL_DL.$EXT.asc" || exit $?
for SUM in "sha512" "sha256"; do
wget "$FULL_DL.$EXT.$SUM" || exit $?
done
done
for SUM in "sha512" "sha256"; do
echo "Validating $SUM checksum..."
"${SUM}sum" --check "$ARCHIVE.$EXT.$SUM" || exit $?
done

for EXT in "tar.gz" "zip" ; do
echo "Validating signature..."
gpg --verify "$ARCHIVE.$EXT.asc" || exit $?
done

if cmake --version >/dev/null ; then
echo "Extracting files..."
tar xf "$ARCHIVE.tar.gz" || exit

cmake -S $ARCHIVE -B test-build || exit
cmake --build test-build || exit
cd test-build
ctest
else
echo "Please install cmake"
fi

0 comments on commit 6583772

Please sign in to comment.