TOMEE-3904: Updates release documentation
diff --git a/src/main/jbake/content/dev/release-tomee.adoc b/src/main/jbake/content/dev/release-tomee.adoc
index a211513..b3dc147 100644
--- a/src/main/jbake/content/dev/release-tomee.adoc
+++ b/src/main/jbake/content/dev/release-tomee.adoc
@@ -2,289 +2,293 @@
:jbake-type: page
:jbake-status: published
- This document is aimed at guiding a release manager through the general release process. You will need either a Linux, Mac, or failing that a Linux Virtual (with at least a 50GB Drive) on Win.
+This document aims to guide a release manager through the general release process.
-== Preparation of The Branch
+== Requirements
-Run menu:ant -f rat.xml[report.txt] on trunk to ensure all licences are in place.
+=== Operating System
-* Review the report.txt and update/add missing headers until clean.
-* _Tip_, search for *Unapproved licenses:* at the beginning of the report for a list.
+You will need either a *Linux* or *Mac*. If you are on a *Windows* machine, you should set up a virtual machine (with at least a 50GB drive).
+Keep in mind, that you have to upload > 1GB of data, that means, ensure to have a stable and fast connection to the internet. Upload bandwidth is key.
-Branch the version to release and ensure it builds and passes all tests.
+=== Java & Maven
-Add a buildbot CI setup for branch here:
+Ensure to build with the correct Java and Maven version.
-https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/tomee.conf
+* TomEE 8.x - Java 8 + Maven 3.3.9
+* TomEE 9.x - Java 11 + Maven 3.8.x
-Basically search for the following line and it should be obvious how to add a new builder:
+Note: Currently, newer Maven version will fail to deploy `*.tar.gz` files correctly. This is tracked in https://issues.apache.org/jira/browse/TOMEE-3903[TOMEE-3903].
- c['builders'].append(tomee_hemera_builder("tomee-trunk-ubuntu", "tomee/tomee/trunk"))
+Ensure to setup `JAVA_HOME` and `PATH` correctly, e.g.:
-An SVN trigger must be added afterwards.
-This can only be done by someone with admin permissions, such as any PMC chair or an Infra team member.
-Just drop an email to _infrastructure@apache.org_
+[source,bash]
+----
+export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-amd64/
+export PATH=$JAVA_HOME/bin:$PATH
+----
-== Create a TCK Branch
+=== Code Signing Setup
-Branch the TCK using the same version as the release branch from here:
+If this is your first release then you will have to ensure that you have a *code signing key* prepared on the machine from which you perform the release.
+The process obtain a valid key is quite intense. You can find information here:
-https://svn.apache.org/repos/tck/tomee-tck/trunk
-
-Update the TCK branch files to point to the version branch.
-
- \tckbranch\plus.properties
- \tckbranch\pom.xml
- \tckbranch\webprofile-plus.properties
- \tckbranch\webprofile.properties
-
-Run menu:ant -f rat.xml[report.txt] on the branch.
-
-* Review the report.txt and update/add missing headers until clean.
-* _Tip_, search for *Unapproved licenses:*.
-
-== Check SVN Authentication
-
-Pre-authenticate svn repositories to ensure your credentials are cached before using any tools.
-
- svn mkdir --username [apacheuser] --password [apachepw] -m "Create test dir" https://svn.apache.org/repos/asf/tomee/tomee/branches/testdir1
- svn delete --username [apacheuser] --password [apachepw] -m "Delete test dir" https://svn.apache.org/repos/asf/tomee/tomee/branches/testdir1
- svn mkdir --username [apacheuser] --password [apachepw] -m "Create test dir" https://repository.apache.org/content/repositories/testdir2
- svn delete --username [apacheuser] --password [apachepw] -m "Delete test dir" https://repository.apache.org/content/repositories/testdir2
- svn mkdir --username [apacheuser] --password [apachepw] -m "Create test dir" https://dist.apache.org/repos/dist/dev/tomee/testdir3
- svn delete --username [apacheuser] --password [apachepw] -m "Delete test dir" https://dist.apache.org/repos/dist/dev/tomee/testdir3
-
-== Prepare Maven Authentication
-
-Ensure your maven .m2/settings.xml correct, and be aware that the tools currently require a clear text password:
-
-....
-<server>
- <id>apache.snapshots.https</id>
- <username>un</username>
- <password>pw.in.clear</password>
-</server>
-
-<server>
- <id>apache.releases.https</id>
- <username>un</username>
- <password>pw.in.clear</password>
-</server>
-
-<server>
- <id>apache.dist.https</id>
- <username>un</username>
- <password>pw.in.clear</password>
-</server>
-
-<profiles>
- <profile>
- ...
- <repositories>
- <repository>
- <id>apache.dist.https</id>
- <url>https://dist.apache.org/repos/dist</url>
- </repository>
- </repositories>
-....
-
-== Code Signing Setup
-
-If this is your first release then you will have to ensure that you have a code signing key prepared on the machine from which you perform the release.
-The process is quite intense.
-You can find information here:
-
-* http://www.apache.org/dev/release-signing.html
-* http://maven.apache.org/developers/release/pmc-gpg-keys.html
+* https://www.apache.org/dev/release-signing.html
+* https://maven.apache.org/developers/release/pmc-gpg-keys.html
However, the basic steps are:
-* Create a key using *gpg --gen-key*, using size 4096 and answering the questions that command issues.
+* Create a key using *gpg --gen-key*, using a keysize of *4096* and answering the questions that command issues.
* During the process you will have to generate random entropy, this is best achieved in another console and issuing the command *find / > /dev/null* and waiting a minute.
* List the keys using *gpg --list-keys* and take note of the name
Once you have your key then you will need to append it to the key file here:
-* http://www.apache.org/dist/tomee/KEYS
+* https://downloads.apache.org/tomee/KEYS
-That is best done as the file itself explains, once you open and view it in a UTF-8 safe text editor you will see the description at the top.
-+ Just follow the instructions there on how to append your key.
-The basic steps are also here, please read both before you proceed:
+Note: Adding new keys via SVN to the **KEYS** files can only be conducted by a PMC member.
+
+That is best done as the file itself explains, once you open and view it in a UTF-8 safe text editor. The basic steps are also here, please read both before you proceed:
* Save the KEYS file on your local machine and import it using *gpg --import KEYS*
* Then create the new KEYS file using **(gpg --list-sigs +++<your name="">+++&& gpg --armor --export +++<your name="">+++) >> KEYS**+++</your>++++++</your>+++
* Check that the new KEYS file contains your key.
-* Log in to people.apache.org and locate /dist/tomee/KEYS
+* Checkout https://dist.apache.org/repos/dist/release/tomee/ via SVN
* Make a backup of the remote KEYS file just in case
-* Overwrite the old /dist/tomee/KEYS file with your new one that now also contains your key.
+* Overwrite the old *KEYS* file with your new one that now also contains your key.
* Go to http://pgp.mit.edu/ and add your ascii armoured key
* Take note of your key fingerprint using **gpg --fingerprint +++<your name="">+++**+++</your>+++
-* Go to https://id.apache.org, log in and fill OpenPGP Public Key Primary Fingerprint: with the value of your fingerprint.
+* Go to https://id.apache.org, log in and fill OpenPGP Public Key Primary Fingerprint with the value of your fingerprint.
+* Create a **backup** of your private and public key and store it in a **save** location.
-== Build the Release Tools
-Checkout the release tools using SVN from here https://svn.apache.org/repos/asf/tomee/sandbox/release-tools
+=== Prepare Maven Authentication
-Really read the README.mdtext and follow the instructions for building the 3rd party libraries.
-+ Basically SVN checkout and compile https://svn.codehaus.org/swizzle/trunk[Swizzle] and https://svn.apache.org/repos/asf/creadur/tentacles/trunk[Tentacles]
-
-Build the release tools, _mvn clean install -DskipTests -DfailIfNoTests=false_
-
-Have a look at *run.sh* to see the entry point.
-
-Understand that the release tools are not polished, and you currently may have to edit source and re-compile.
-
-== Site Staging <<staging,>> For some of the release steps you will need to provide documentation on the site.
-Checkout the site here:
-
-https://svn.apache.org/repos/asf/tomee/site/trunk
-
-Most of the content can be found under 'content' and subdirectories.
-
-When you commit changes the site should be built automatically by the buildbot, but you can force a build on IRC using:
-
- **tomee-bot: force build tomee-site-staging**
-
-The buildbot staging result can be seen here:
-
-http://ci.apache.org/builders/tomee-site-staging
-
-And the actual staging site, where you can review your changes, is here:
-
-http://tomee.staging.apache.org/
-
-Once you are happy with the staging you can publish to the real site using:
-
-https://cms.apache.org/tomee/publish
-
-== Begin The Release Process
-
-Ensure TCK is passing all tests, and if so create an SVN tag from the branch.
+Ensure your maven `.m2/settings.xml` are setup correctly and be aware that the tools currently require a clear text password:
....
-Note: It is a future goal to either separate OpenEJB from TomEE or unify the versions so the
-[maven-release-plugin](http://maven.apache.org/maven-release/maven-release-plugin/) can be used.
-
-Because we cannot use the Maven release tools we currently have to create a an SVN tag manually. The best way to do this is to:
-
- - Copy the branch to a staging branch using:
- > svn copy https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version] https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging -m "Staging [version]"
- - Checkout the staging branch using:
- > svn co https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging tomee-[version]-staging
- - Update all SNAPSHOT versions to the release versions in the local tomee-[version]-staging and commit.
- - Create the tag from the staging:
- > svn copy https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging https://svn.apache.org/repos/asf/tomee/tomee/tags/tomee-[version] -m "Tag [version]"
- - Delete the staging branch using:
- > svn rm https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging -m "Delete staging"
+ <servers>
+ <server>
+ <id>apache.snapshots.https</id>
+ <username>ASF_LDAP</username>
+ <password>ASF_PASSWORD_IN_CLEAR</password>
+ </server>
+ <server>
+ <id>apache.releases.https</id>
+ <username>ASF_LDAP</username>
+ <password>ASF_PASSWORD_IN_CLEAR</password>
+ </server>
+ <server>
+ <id>apache.dist.https</id>
+ <username>ASF_LDAP</username>
+ <password>ASF_PASSWORD_IN_CLEAR</password>
+ </server>
+ </servers>
+<profiles>
+ <profile>
+ <id>my_profile</id>
+ <properties>
+ <gpg.keyname>INSERT_YOUR_GPG_FINGERPRINT</gpg.keyname>
+ </properties>
+ <repositories>
+ <repository>
+ <id>apache.dist.https</id>
+ <url>https://dist.apache.org/repos/dist</url>
+ </repository>
+ </repositories>
+ </profile>
+</profiles>
....
-Open a console on the release-tools directory.
-NOTE: Before running any *./run.sh* activity always check the release tools code for the command tomee-release-tools/src/main/java/org/apache/openejb/tools/release/cmd.
-At the moment some of the commands need manually editing to work.
-Eventually the commands should be re-written.
+=== Check SVN Authentication
-All JIRA actions should be performed on the ASF JIRA here:
+Pre-authenticate SVN repositories to ensure your credentials are cached before using any tools.
-https://issues.apache.org/jira/browse/TOMEE
+ svn mkdir --username [ASF_LDAP] --password [ASF_PASSWORD] -m "Create test dir" https://dist.apache.org/repos/dist/dev/tomee/testdir3
+ svn delete --username [ASF_LDAP] --password [ASF_PASSWORD] -m "Delete test dir" https://dist.apache.org/repos/dist/dev/tomee/testdir3
-Ensure JIRAs have been filed for commits using *./run.sh reviewcommits*
+== Preparation of the release
-Update fixVersions for JIRAs used in SVN commits using *./run.sh updatejiras* - _Untested, requires investigation_
+=== Check Licenses & Style
-Review and bulk Close all JIRAs for the version to be released.
+Run
-Publish the changed binaries report (if any) using *./run.sh comparelibraries*
+[source,bash]
+----
+mvn help:system -U --show-version --fail-at-end clean install -DfailIfNoTests=false -DskipTests -Pstyle,rat
+----
-Write and publish the release notes preview on the staging site.
+to ensure all licences are in place.
-Publish a summary of the RAT report preview on the staging site.
+* Review the report.txt and update/add missing headers until clean.
+* Search for *Unapproved licenses:* at the beginning of the report for a list.
-Using the RAT report as a guide update LICENSE and NOTICE files for any changed binaries, and add new ones if required.
+Note: This step is always run by the GitHub Actions workflow **and** by the Jenkins build server, so you can check the CI status:
-Update branch versions.
-How you do this is up to you at this point in time.
+* https://ci-builds.apache.org/job/Tomee/job/master-sanity-checks/[TomEE Master Sanity Checks]
+* https://ci-builds.apache.org/job/Tomee/job/tomee-8.x-sanity-checks/[TomEE 8.x Sanity Checks]
-Update trunk versions.
-How you do this is up to you at this point in time.
+=== Check the full builds
-Create the next version iterations in JIRA.
+Before you can continue, you should check, that the **full** build on Jenkins CI passes *all* tests.
-== Rolling Out The Preview
+* https://ci-builds.apache.org/job/Tomee/job/master-build-full/[TomEE Master]
+* https://ci-builds.apache.org/job/Tomee/job/tomee-8.x-build-full/[TomEE 8.x]
-....
-Note: Before running anything below ensure you either have:
+=== Run the TCK (optional)
- - A valid tomee-release.properties from the last release in your home directory (Speak to the last release manager).
- - Or have modified **tomee-release-tools/src/main/java/org/apache/openejb/tools/release/Release.java** with current versions and **mvn clean install**.
-....
+If in doubt, it makes sense to run the TCK on dedicated infrastructure.
+Instruction can be found in the https://github.com/apache/tomee-tck[TCK harness repository].
-Ensure the TCK passes with preview repositories by editing and ensuring paths are correct in the following files:
+=== Build the Release Tools
- \tckbranch\plus.properties
- \tckbranch\pom.xml
- \tckbranch\webprofile-plus.properties
- \tckbranch\webprofile.properties
+Checkout the release tools using git from https://github.com/apache/tomee-release-tools
-Publish the preview using *./run.sh roll binaries legal releasenotes preview* - You can run these tasks like so, or individually in order.
-It will be likely that this will have to be repeated several times before a successful vote.
+* **Read** the `README.adoc` and follow the instructions for building required 3rd party libraries, i.e., checkout https://svn.apache.org/repos/asf/creadur/tentacles/trunk[Tentacles] and build them.
-The _legal_ step will create the legal report files in the /tmp/download/staging-[revision]/legal directory.
-These need to be added to the staging repo.
+* Build the release tools by running `mvn clean install`
-* Delete the [legal]/repo and [legal]/content directories, as these are no longer required rm -R /tmp/download/staging-[revision]/legal/content rm -R /tmp/download/staging-[revision]/legal/repo
-* Perform a non-recursive checkout of the staging repo and add the legal: svn co -N https://dist.apache.org/repos/dist/dev/tomee/staging-[revision] /tmp/download/staging mv /tmp/download/staging-[revision]/legal /tmp/download/staging cd /tmp/download/staging-[revision] svn add legal
+* The build will create an executable, which can be run via `./target/release`.
-Once the binaries are in place add the staging repository to the corresponding TCK project and fire off a build.
-To fire off a build on EC2 from the TCK directory speak to the last release manager for the *curl* command to use
+* Understand that the release tools are not polished, and you currently may have to edit source and re-compile.
-If the TCK fails then discuss, fix and re-roll.
-Publish a https://www.apache.org/foundation/voting.html[Vote] if, and only if, the TCK passes.
+== Begin the Release process
-Votes are generally managed and identified using keywords such as [VOTE], [CANCELLED] and [RESULT]
+=== Build the project
-If the vote fails then discuss, fix and re-roll.
+Double check that the tests and (optionally) the TCK passes. If so, go ahead with
-== Voted Binaries
+[source,bash]
+----
+mvn clean install release:prepare -DskipTests=true -Pmy_profile
+----
-Once the vote has passed then release the binaries on Nexus: https://repository.apache.org/index.html#welcome
+The `release:prepare` will ask some interactive questions, which need to be answered. If you are unsure, you can specify `-DdryRun=true` to test it beforehand.
-Update both OpenEJB and TomEE JIRA versions as released (Set the release date).
+This command will create a tag and update the POM files accordingly to the release and the next development iteration.
-Copy the binaries to the release location (User rights require a PMC to do this)
+During this process a `release.properties` is created in the project root, which you should copy to a save location in case something goes wrong.
+
+=== Deploy to Nexus Staging Area
+
+If everything was successful, you can then run
+
+[source,bash]
+----
+mvn release:perform -DskipTests=true -Pmy_profile
+----
+
+This will take some time and upload a bunch of data to https://repository.apache.org/
+
+After the build succeeds:
+
+* Login into https://repository.apache.org/
+
+* Go to **Staging Repositories**
+
+* Find the auto-generated staging repository named **orgapachetomee-xxxx**
+
+* Double-check the content of the repository. For example:
+
+** Check if `*.tar.gz` distribution artifacts are correctly uploaded.
+** Check that `*.asc` signatures are present.
+
+* If your checks are ok, you can **close** the staging repository and move on.
+
+=== Deploy Source and Distributions to dist/dev
+
+Next, we need to move the distribution bundles (source + zip + tar.gz) to https://dist.apache.org/repos/dist/dev/tomee/
+
+To do so, open the `tomee-release-tools`, which you have build in an earlier step.
+
+Run
+
+[source,bash]
+----
+./target/release dist maven-to-dev --dry-run --maven-repo=https://repository.apache.org/content/repositories/orgapachetomee-xxxx/ VERSION
+----
+
+and replace `xxxx` with the staging repository and `VERSION` with the actual version to perform the release.
+
+This will download the required distribution bundles from the staging repository and generate SHA256 / SHA512 hashes.
+
+Check that the files were correctly downloaded and the created folder in `/tmp` contains everything, which is expected for the release (i.e. hashes, gpg sigs, sources, tar.gz and zip files).
+
+If everything is **ok**, remove the `--dry-run` flag and execute:
+
+[source,bash]
+----
+./target/release dist maven-to-dev --maven-repo=https://repository.apache.org/content/repositories/orgapachetomee-xxxx/ VERSION
+----
+
+This will download the required distribution bundles from the staging repository and generate SHA256 / SHA512 hashes and commit everything to https://dist.apache.org/repos/dist/dev/tomee/.
+
+*Note:* Committing the changes will take some time depending on your upload bandwidth. Ensure you have a stable connection.
+
+After the upload was successful, check that everything you would expect is available in https://dist.apache.org/repos/dist/dev/tomee/
+
+=== Push the commits and the tag
+
+Now it is time to push the generated commits *and* the tag generated during `release:prepare`.
+
+[source,bash]
+----
+git push origin <branch>
+git push origin <tagname>
+----
+
+=== Generate release notes (website)
+
+Next, you can use `tomee-release-tools` to generate the release notes for the website.
+
+[source,bash]
+----
+./target/release release-notes generate VERSION
+----
+
+Create a new branch on https://github.com/apache/tomee-site-generator/[tomee-site-generator] and add a new directory to `src/main/jbake/content/<VERSION>`.
+Copy the output of the command above to a new file `release-notes.adoc`.Write some sentences summarizing the release and thank all users / contributors, who submitted bug reports, contributed code or documentation for the given release.
+You can also get inspiration from previous release notes.
+
+In addition, prepare the download pages and move the old version to the download archive.
+
+=== Generate release notes (Jira)
+
+* Go to https://issues.apache.org/jira/browse/TOMEE[ASF Jira]
+* Navigate to https://issues.apache.org/jira/projects/TOMEE?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=all[Releases]
+* Create the next version, if it does not exist
+* Move all unresolved issues from the previous version to the new version (this is a bulk action)
+* Navigate to the version, which should be released, and click on **Release Notes**.
+* Verify, that the **Release Notes** only contain resolved issues.
+* Save the permalink to the release notes in Jira as we need it for the VOTE.
+
+== Calling for a vote (PMC only)
+
+* Publish a https://www.apache.org/foundation/voting.html[Vote].
+
+* Votes are generally managed and identified using keywords such as [VOTE], [CANCELLED] and [RESULT]
+
+* Include links to the staging repository, to dev/dist and to the tag created.
+
+* Include the changelog and a link to the Jira release notes
+
+* If the vote fails then discuss, fix and re-roll.
+
+== Voted Binaries (PMC only)
+
+* Once the vote has passed then release the binaries on Nexus: https://repository.apache.org/
+
+* Update both OpenEJB and TomEE JIRA versions as released (Set the release date).
+
+* Copy the binaries to the release location
From: https://dist.apache.org/repos/dist/dev/tomee/staging-[stagingId]/tomee-[version]
To: https://dist.apache.org/repos/dist/release/tomee/tomee-[version]
-Wait for the binaries to replicate to mirrors.
-Here is a neat script from David to check the status:
+* Merge the website branch and trigger a https://ci-builds.apache.org/job/Tomee/job/site-publish/[site deploy via Jenkins].
-....
-#!/bin/bash
-
-RELEASE=${1?Specify a release, such as './mirror_check.sh tomee-1.7.1'}
-
-function list_mirrors {
- DYN=http://www.apache.org/dyn/closer.cgi/tomee/$RELEASE/
- wget -q -O - $DYN | tr '">< ' '\n' | grep "^http.*$RELEASE/" | sort | uniq
-}
-
-function status_code {
- wget -v "$1" 2>&1| grep 'awaiting response' | tr ' ' '\n' | grep "[0-9]"
-}
-
-list_mirrors | while read n; do
- echo "$(status_code $n) $n"
-done | sort | grep 'http'
-....
-
-Commit and publish changes to the site, see xref:release-tomee.adoc#staging[Site Staging]
-
- https://cms.apache.org/tomee/publish
-
-== Blog
+== Spread the word!
Announce to the world that TomEE has new bells and whistles!
-
-https://blogs.apache.org/roller-ui/login.rol + http://twitter.com/ApacheTomEE + http://facebook.com/ApacheTomEE
