Provide guidelines and templates for the release process (#413)

admin/MailTemplate.Announce.txt

@@ -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

admin/MailTemplate.Result.txt

@@ -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.
+
+...

admin/MailTemplate.txt

@@ -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.

admin/release-review-instructions.md

@@ -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`

admin/releasing.md

@@ -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)
+

admin/staging.md

@@ -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
+

admin/validate-release.sh

@@ -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
+