This is an automated email from the ASF dual-hosted git repository.
rzo1 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomee-site-generator.git
The following commit(s) were added to refs/heads/master by this push:
new 35c3def TOMEE-3904: Updates release documentation
35c3def is described below
commit 35c3def21bad0e30cba5f350eb99318255c97a56
Author: Richard Zowalla <[email protected]>
AuthorDate: Thu Apr 14 08:48:17 2022 +0200
TOMEE-3904: Updates release documentation
---
src/main/jbake/content/dev/release-tomee.adoc | 382 +++++++++++++-------------
1 file changed, 193 insertions(+), 189 deletions(-)
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 [email protected]_
+[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
+* https://www.apache.org/dev/release-signing.html
+* https://maven.apache.org/developers/release/pmc-gpg-keys.html
-Update the TCK branch files to point to the version branch.
+However, the basic steps are:
- \tckbranch\plus.properties
- \tckbranch\pom.xml
- \tckbranch\webprofile-plus.properties
- \tckbranch\webprofile.properties
+* 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
-Run menu:ant -f rat.xml[report.txt] on the branch.
+Once you have your key then you will need to append it to the key file here:
-* Review the report.txt and update/add missing headers until clean.
-* _Tip_, search for *Unapproved licenses:*.
+* https://downloads.apache.org/tomee/KEYS
-== Check SVN Authentication
+Note: Adding new keys via SVN to the **KEYS** files can only be conducted by a
PMC member.
-Pre-authenticate svn repositories to ensure your credentials are cached before
using any tools.
+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.
+* 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 *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.
+* Create a **backup** of your private and public key and store it in a
**save** location.
- 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
+=== Prepare Maven Authentication
-Ensure your maven .m2/settings.xml correct, and be aware that the tools
currently require a clear text password:
+Ensure your maven `.m2/settings.xml` are setup correctly 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>
-
+ <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>
- ...
- <repositories>
- <repository>
- <id>apache.dist.https</id>
- <url>https://dist.apache.org/repos/dist</url>
- </repository>
- </repositories>
+ <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>
....
-== 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:
+=== Check SVN Authentication
-* http://www.apache.org/dev/release-signing.html
-* http://maven.apache.org/developers/release/pmc-gpg-keys.html
+Pre-authenticate SVN repositories to ensure your credentials are cached before
using any tools.
-However, the basic steps are:
+ 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
-* Create a key using *gpg --gen-key*, using size 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
+== Preparation of the release
-Once you have your key then you will need to append it to the key file here:
+=== Check Licenses & Style
-* http://www.apache.org/dist/tomee/KEYS
+Run
-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:
+[source,bash]
+----
+mvn help:system -U --show-version --fail-at-end clean install
-DfailIfNoTests=false -DskipTests -Pstyle,rat
+----
-* 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
-* 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.
-* 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.
+to ensure all licences are in place.
-== Build the Release Tools
+* Review the report.txt and update/add missing headers until clean.
+* Search for *Unapproved licenses:* at the beginning of the report for a list.
-Checkout the release tools using SVN from here
https://svn.apache.org/repos/asf/tomee/sandbox/release-tools
+Note: This step is always run by the GitHub Actions workflow **and** by the
Jenkins build server, so you can check the CI status:
-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]
+* 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]
-Build the release tools, _mvn clean install -DskipTests -DfailIfNoTests=false_
+=== Check the full builds
-Have a look at *run.sh* to see the entry point.
+Before you can continue, you should check, that the **full** build on Jenkins
CI passes *all* tests.
-Understand that the release tools are not polished, and you currently may have
to edit source and re-compile.
+* 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]
-== Site Staging <<staging,>> For some of the release steps you will need to
provide documentation on the site.
-Checkout the site here:
+=== Run the TCK (optional)
-https://svn.apache.org/repos/asf/tomee/site/trunk
+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].
-Most of the content can be found under 'content' and subdirectories.
+=== Build the Release Tools
-When you commit changes the site should be built automatically by the
buildbot, but you can force a build on IRC using:
+Checkout the release tools using git from
https://github.com/apache/tomee-release-tools
- **tomee-bot: force build tomee-site-staging**
+* **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 buildbot staging result can be seen here:
+* Build the release tools by running `mvn clean install`
-http://ci.apache.org/builders/tomee-site-staging
+* The build will create an executable, which can be run via
`./target/release`.
-And the actual staging site, where you can review your changes, is here:
+* Understand that the release tools are not polished, and you currently may
have to edit source and re-compile.
-http://tomee.staging.apache.org/
-Once you are happy with the staging you can publish to the real site using:
+== Begin the Release process
-https://cms.apache.org/tomee/publish
+=== Build the project
-== Begin The Release Process
+Double check that the tests and (optionally) the TCK passes. If so, go ahead
with
-Ensure TCK is passing all tests, and if so create an SVN tag from the branch.
+[source,bash]
+----
+mvn clean install release:prepare -DskipTests=true -Pmy_profile
+----
-....
-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"
-....
+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.
-Open a console on the release-tools directory.
+This command will create a tag and update the POM files accordingly to the
release and the next development iteration.
-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.
+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.
-All JIRA actions should be performed on the ASF JIRA here:
+=== Deploy to Nexus Staging Area
-https://issues.apache.org/jira/browse/TOMEE
+If everything was successful, you can then run
-Ensure JIRAs have been filed for commits using *./run.sh reviewcommits*
+[source,bash]
+----
+mvn release:perform -DskipTests=true -Pmy_profile
+----
-Update fixVersions for JIRAs used in SVN commits using *./run.sh updatejiras*
- _Untested, requires investigation_
+This will take some time and upload a bunch of data to
https://repository.apache.org/
-Review and bulk Close all JIRAs for the version to be released.
+After the build succeeds:
-Publish the changed binaries report (if any) using *./run.sh comparelibraries*
+* Login into https://repository.apache.org/
-Write and publish the release notes preview on the staging site.
+* Go to **Staging Repositories**
-Publish a summary of the RAT report preview on the staging site.
+* Find the auto-generated staging repository named **orgapachetomee-xxxx**
-Using the RAT report as a guide update LICENSE and NOTICE files for any
changed binaries, and add new ones if required.
+* Double-check the content of the repository. For example:
-Update branch versions.
-How you do this is up to you at this point in time.
+** Check if `*.tar.gz` distribution artifacts are correctly uploaded.
+** Check that `*.asc` signatures are present.
-Update trunk versions.
-How you do this is up to you at this point in time.
+* If your checks are ok, you can **close** the staging repository and move on.
-Create the next version iterations in JIRA.
+=== Deploy Source and Distributions to dist/dev
-== Rolling Out The Preview
+Next, we need to move the distribution bundles (source + zip + tar.gz) to
https://dist.apache.org/repos/dist/dev/tomee/
-....
-Note: Before running anything below ensure you either have:
+To do so, open the `tomee-release-tools`, which you have build in an earlier
step.
- - 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**.
-....
+Run
-Ensure the TCK passes with preview repositories by editing and ensuring paths
are correct in the following files:
+[source,bash]
+----
+./target/release dist maven-to-dev --dry-run
--maven-repo=https://repository.apache.org/content/repositories/orgapachetomee-xxxx/
VERSION
+----
- \tckbranch\plus.properties
- \tckbranch\pom.xml
- \tckbranch\webprofile-plus.properties
- \tckbranch\webprofile.properties
+and replace `xxxx` with the staging repository and `VERSION` with the actual
version to perform the release.
-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.
+This will download the required distribution bundles from the staging
repository and generate SHA256 / SHA512 hashes.
-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.
+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).
-* 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
+If everything is **ok**, remove the `--dry-run` flag and execute:
-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
+[source,bash]
+----
+./target/release dist maven-to-dev
--maven-repo=https://repository.apache.org/content/repositories/orgapachetomee-xxxx/
VERSION
+----
-If the TCK fails then discuss, fix and re-roll.
+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/.
-Publish a https://www.apache.org/foundation/voting.html[Vote] if, and only if,
the TCK passes.
+*Note:* Committing the changes will take some time depending on your upload
bandwidth. Ensure you have a stable connection.
-Votes are generally managed and identified using keywords such as [VOTE],
[CANCELLED] and [RESULT]
+After the upload was successful, check that everything you would expect is
available in https://dist.apache.org/repos/dist/dev/tomee/
-If the vote fails then discuss, fix and re-roll.
+=== Push the commits and the tag
-== Voted Binaries
+Now it is time to push the generated commits *and* the tag generated during
`release:prepare`.
-Once the vote has passed then release the binaries on Nexus:
https://repository.apache.org/index.html#welcome
+[source,bash]
+----
+git push origin <branch>
+git push origin <tagname>
+----
-Update both OpenEJB and TomEE JIRA versions as released (Set the release date).
+=== Generate release notes (website)
-Copy the binaries to the release location (User rights require a PMC to do
this)
+Next, you can use `tomee-release-tools` to generate the release notes for the
website.
- From:
https://dist.apache.org/repos/dist/dev/tomee/staging-[stagingId]/tomee-[version]
- To: https://dist.apache.org/repos/dist/release/tomee/tomee-[version]
+[source,bash]
+----
+./target/release release-notes generate VERSION
+----
-Wait for the binaries to replicate to mirrors.
-Here is a neat script from David to check the status:
+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.
-....
-#!/bin/bash
+In addition, prepare the download pages and move the old version to the
download archive.
-RELEASE=${1?Specify a release, such as './mirror_check.sh tomee-1.7.1'}
+=== Generate release notes (Jira)
-function list_mirrors {
- DYN=http://www.apache.org/dyn/closer.cgi/tomee/$RELEASE/
- wget -q -O - $DYN | tr '">< ' '\n' | grep "^http.*$RELEASE/" | sort | uniq
-}
+* 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.
-function status_code {
- wget -v "$1" 2>&1| grep 'awaiting response' | tr ' ' '\n' | grep "[0-9]"
-}
+== Calling for a vote (PMC only)
-list_mirrors | while read n; do
- echo "$(status_code $n) $n"
-done | sort | grep 'http'
-....
+* Publish a https://www.apache.org/foundation/voting.html[Vote].
-Commit and publish changes to the site, see
xref:release-tomee.adoc#staging[Site Staging]
+* Votes are generally managed and identified using keywords such as [VOTE],
[CANCELLED] and [RESULT]
- https://cms.apache.org/tomee/publish
+* Include links to the staging repository, to dev/dist and to the tag created.
-== Blog
+* Include the changelog and a link to the Jira release notes
-Announce to the world that TomEE has new bells and whistles!
+* 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/
-https://blogs.apache.org/roller-ui/login.rol + http://twitter.com/ApacheTomEE
+ http://facebook.com/ApacheTomEE
+* 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]
+
+* Merge the website branch and trigger a
https://ci-builds.apache.org/job/Tomee/job/site-publish/[site deploy via
Jenkins].
+
+== Spread the word!
+
+Announce to the world that TomEE has new bells and whistles!
