Update HowToReleaseJDO.md (#19)
diff --git a/HowToReleaseJDO.md b/HowToReleaseJDO.md
index 5dbbb09..162353d 100644
--- a/HowToReleaseJDO.md
+++ b/HowToReleaseJDO.md
@@ -22,9 +22,12 @@
How to Release an Apache JDO Distribution
=========================================
-A distribution of JDO is built from a branch of the git repository. It is copied into a
-release directory, from which it is staged and tested prior to release.
-Once released, it is propagated to mirror servers around the world.
+A distribution (release) of JDO is built from a branch of git. A release
+consists of a compressed source (e.g. zip file) and associated checksums and
+signatures. It is copied into a release directory, from which it is staged
+and tested.
+Once approved by a formal vote of the DB PMC, it is copied to the officiel
+Apache distribution infrastructure and propagated to mirror servers around the world.
The process is performed by a release manager with cooperation from
testers in the community.
@@ -36,8 +39,8 @@
The community first decides on the name of the release. The format of
the name is *spec-number*.*major*.*minor*. A trailing *minor* number
-with a zero value is right trimmed, so there might be a 2.0.1 but not a
-2.0.0.
+with a zero value is right trimmed, so there might be a 3.0.1 but not a
+3.0.0.
Interim releases prior to final release are identified by a suffix on
the release number. Common suffixes include: -alpha, -beta, -beta2,
@@ -46,9 +49,13 @@
might be significant changes in functionality between the suffix
releases. Each suffix release goes through the process documented here.
-The release manager makes a branch from the trunk (for a major release)
-or from another branch (for a minor release) to create a branch with the
-source of the distribution.
+The community decides whether to continue development on the main branch
+while the release is in progress. In this case, a branch is created
+first. If a new branch is needed, the release manager makes a new branch
+from the main branch (for a major release) or from another branch (for
+a minor release). If a new branch is not needed, the release will be
+created from the main branch and a release branch will only be created
+later for a maintenance release.
The release manager follows the Apache process detailed below to build
and deploy a release.
@@ -58,16 +65,19 @@
The community tests the release. If necessary, cycle until all issues
are resolved.
-The release manager closes the staged repository
+The release manager closes the staging repository
The release manager calls for a vote to release by sending a message to
-the community and forwarding the message to the pmc.
+the community and forwarding the message to the PMC.
The community votes on the release. If necessary, cycle until issues are
resolved.
-The release manager notifies the pmc of the successful vote outcome.
-Note that a successful vote includes three +1 votes from PMC members.
+The release manager notifies the PMC of the successful vote outcome.
+A successful vote includes three +1 votes from PMC members and more +1
+than -1 votes.
+The release manager copies the approved release to the official Apache
+distribution directory which is then mirrored worldwide.
The release manager notifies the worldwide community of the availability
of the release.
@@ -77,31 +87,30 @@
If bugs are found or test challenges are sustained after the release is
approved and distributed, the release manager creates a new branch to
-address the bugs found.
+address the bugs found and proceeds from the beginning.
<span id="procdetail"></span>
Detailed process steps
----------------------
-1. You might want to run [Apache Rat](http://creadur.apache.org/rat) to
- check the sources for any lisence issues.
+1. Verify licensing of the sources by running
+ [Apache Rat](http://creadur.apache.org/rat) to
+ check the sources for any licence issues.
- mvn apache-rat:check
+ mvn clean apache-rat:check
-2. Create a branch from the trunk and increment the spec or major
- number. For example, create a 3.1 branch from the trunk.
+2. If necessary, create a branch from the main branch and increment the
+ spec or major number. For example, create a "3.1" branch from the
+ main branch.
- cd jdo
- svn copy https://svn.apache.org/repos/asf/db/jdo/trunk \
- https://svn.apache.org/repos/asf/db/jdo/branches/3.1
+ git checkout -b 3.2
+ git push -u 3.2
-3. In trunk, update version numbers in the following files in
+3. In the release branch, update version numbers in the following files in
preparation for the next release:
- trunk/README.html
- File names and version references in the Overview section
-
- trunk/tck/RunRules.html
+
+ tck/README.md
Update version number and date
Use the maven version plug-in to update version numbers in the
@@ -110,21 +119,20 @@
4. If needed, update the dependency to the RI, DataNucleus, in the tck
pom.xml.
-5. If needed, apply patches from the trunk or branches to the new
- branch.
+5. If needed, apply patches from the main branch to the release branch.
6. Update version numbers where necessary in projects to be released,
if these changes haven't been made previously. Check the following
files:
- branches/*version*/README.html
+ README.md
File names and version references in the Overview section (for a
major release only.)
- branches/*version*/tck/RunRules.html
+ tck/RunRules.md
Update version number
7. Check the scm settings in the pom.xml files in the new branch and
- make sure they refer the new branch (instead of the trunk).
+ make sure they refer to the new branch (instead of the main branch).
8. Follow the instructions at [Publishing Maven
Artifacts](http://www.apache.org/dev/publishing-maven-artifacts.html)
@@ -132,92 +140,99 @@
9. Copy the JNDI implementation jars (providerutil.jar and
fscontext.jar) to the branch lib/ext directory. This is needed to
- test the tck before distributing it.**
- Do not check these in to SVN**
+ test the tck before distributing it.
+ **Do not check these in into the repository**
-10. Build the distribution with the following command:
+10. Make sure the TCK passes
- mvn clean install -Papache-release
-
+ mvn clean install
+11. Build the distribution with the following command:
+
+ mvn clean install -Papache-release -Djdo.tck.doRunTCK=false -Djdo.tck.doInstallSchema=false -Djdo.tck.doEnhance=false
+
This creates the .jar and .pom files in the target directory of each
- subproject. Be prepared to enter your key passcode when prompted.
+ subproject. Be prepared to enter your key passcode when prompted,
+ to create the <artifact>.asc GPG signatures.
This happens multiple times.
-11. Run [Apache Rat](http://creadur.apache.org/rat) on the release.
+12. Run [Apache Rat](http://creadur.apache.org/rat) on the release
+ artifacts to verify the results of the build.
-12. Do a dry run prepare and deployment of a snapshot release. You might
+ Download Apache Rat from https://creadur.apache.org/rat/download_rat.cgi
+ and extract the Jar-File, e.g. apache-rat-0.13.jar
+
+ java -jar apache-rat-0.13.jar -E .rat-excludes -d api/target/jdo-api-3.2-SNAPSHOT-sources.jar
+ java -jar apache-rat-0.13.jar -E .rat-excludes -d tck/target/jdo-tck-3.2-SNAPSHOT-sources.jar
+
+13. Do a dry run prepare and deployment of a *snapshot release*. You might
want to do this in a fresh workspace, since you cannot have local
modifications when preparing a release. The files in lib/ext and
lib/jdori count as local modifications. Be prepared to enter your
key passcode when prompted. This happens multiple times.
- mvn release:prepare -Papache-release -DautoVersionSubmodules=true -DdryRun=true -Dresume=false
+ The release plugin will will ask the following questions and expects an input:
+ What is the release version for "JDO Root POM"?
+ What is the SCM release tag or label for "JDO Root POM"?
+ What is the new development version for "JDO Root POM"?
+ The proposed defaults should be fine.
- mvn deploy -Papache-release
-
-
+ mkdir tmp
+ cd tmp
+ git clone https://github.com/apache/db-jdo.git
+ cd db-jdo
+ mvn release:prepare -Papache-release -DautoVersionSubmodules=true -DdryRun=true -Dresume=false
+ mvn deploy -Papache-release
+
Check the artifacts at [the Maven release
repository](https://repository.apache.org/content/repositories/snapshots/)
-13. Prepare and release the artifacts. There are interoperability issues
+14. Prepare and release the artifacts. There are interoperability issues
with the maven release plugin and cygwin, so if on Windows, use a
Windows command window for this step and the following one.
mvn release:clean -Papache-release
mvn release:prepare -Papache-release
-
- Note: If you're located in Europe then release:prepare may fail with
- 'Unable to tag SCM' and ' svn: No such revision X '. Wait 10 seconds
- and run mvn release:prepare again.
-
-14. Stage the release for a vote.
+15. Stage the release for a vote.
mvn release:perform -Papache-release
-
-15. Go to [the Nexus
+16. Go to [the Nexus
repository](https://repository.apache.org/index.html), login with
your apache account, click on Staging Repositories in the menu on
the left and close the staged repository. Press the refresh button
- to see the new status 'closed'. See [11.4.1. Closing an Open
- Repository](http://books.sonatype.com/nexus-book/reference/staging-repositories.html)
+ to see the new status 'closed'. See [Closing an Open Repository](https://help.sonatype.com/repomanager2/staging-releases/managing-staging-repositories#ManagingStagingRepositories-ClosinganOpenRepository)
for details.
-16. Send an announcement to test the release to the
+17. Send an announcement (e.g. Subject: Please test staged JDO 3.2 release)
+ to test the release to the
jdo-dev@db.apache.org alias. If problems are found, fix and repeat.
-17. Send an announcement to vote on the release to the
+18. Send an announcement to vote on the release to the
jdo-dev@db.apache.org alias. The message subject line contains
\[VOTE\]. Forward the \[VOTE\] message to private@db.apache.org.
Iterate until you get a successful vote. Mail the results of the
vote to jdo-dev@db.apache.org, cc: general@db.apache.org, and
include \[VOTE\] \[RESULTS\] in the subject line.
-18. After testing and voting is complete, follow the instructions at
- [11.4.3. Releasing a Staging
- Repository](http://books.sonatype.com/nexus-book/reference/staging-repositories.html)
+19. After testing and voting is complete, follow the instructions at
+ [Releasing a Staging Repository](https://help.sonatype.com/repomanager2/staging-releases/managing-staging-repositories#ManagingStagingRepositories-ReleasingaStagingRepository)
to release the artifacts.
-19. Update the distribution repository at http://apache.org/dist/db/jdo/
- by adding the new release directory to the svnpubsub directory.
- Check out the repository at
+20. Update the distribution repository at https://apache.org/dist/db/jdo/
+ by adding the new release directory.
+ Check out the SVN repository at
https://dist.apache.org/repos/dist/release/db/jdo and add the new
release with all artifacts under the new directory. Make sure that
the key used to sign the artifacts is included in the KEYS file.
Committing the new directory will trigger an update to the mirrors.
-20. If the release is a bug fix release to a maintenance release, update
- README.txt in the parent branch, adding the following line: "This
- release has been deprecated. Please use version 2.x.y.", with a link
- to the svn web interface for that version.
-
21. After updating the site (below), announce the release to the Apache
community via email to announce@apache.org This must be sent from an
- @apache.org email address. \*\*\* Be aware that by sending to this
+ @apache.org email address. **Be aware that by sending to this
address you will be bombarded with piles of emails from people with
- "I'm out of the Office" as if you really cared \*\*\*
+ "I'm out of the Office" as if you really cared.**
<span id="site"></span>
@@ -226,34 +241,18 @@
1. Update the Apache JDO web site to point the downloads page to the
release.
- 1. In site/src/site/xdoc/releases create release-*N.n*.xml. Edit
- the release numbers and the link to the release notes. You will
- need to change the '&'s in the URL to "&"
+ 1. In [dbo-jdo-site/src/main/asciidoc](https://github.com/apache/db-jdo-site/tree/master/src/main/asciidoc)
+ create release-*N.n*.adoc.
- 2. In site/src/site/resources/releases create release-*N.n*.cgi.
- The .cgi file contents are identical to the other .cgi files in
- the release directory; only the file name differs.
+ 2. Edit db-jdo-site/src/main/asciidoc/downloads.adoc to link to the
+ new release page .adoc document.
- 3. Edit site/src/site/xdoc/downloads.xml to link to the new release
- page .cgi document.
-
- 4. Build and test as described in the site/HOWTO document. Note
- that the cgi page will not be active until it is on the server,
- so can't really be tested.
-
- 5. Add the new files to the subversion repository.
-
- svn add site/src/site/xdoc/releases/release-N.n.xml
- svn add site/docs/releases/release-N.n.html
- svn add site/src/site/resources/releases/release-N.n.cgi
- svn add site/docs/releases/release-N.n.cgi
-
-
- 6. Set the svn properties svn:eol-style to native and
- svn:executable to true for the .cgi files.
+ 3. Build and test as described in the [db-jdo-site/README.md](https://github.com/apache/db-jdo-site/blob/master/README.md)
+ document.
+
2. Change the link to RunRules on the
[TCK](http://db.apache.org/jdo/tck.html) page to link to the
- RunRules.html file of the latest release.
+ RunRules.md file of the latest release.
3. Update the news list on the site home page to announce the new
release.
4. Update the specification page to link to the new specification pdf
@@ -261,15 +260,15 @@
documentation page of the JCP web site. If the release has not been
approved by the JCP, link to the .pdf in the JDO source repository.
5. Add the javadoc for the release to the site.
- 1. Make a new directory under site/docs for the release, e.g.
- api2.1. We'll call it *docsdir*.
+ 1. Make a new directory under [db-jdo-site/src/main/resources/javadoc](https://github.com/apache/db-jdo-site/tree/master/src/main/resources/javadoc)
+ for the release, e.g. api2.1. We'll call it *docsdir*.
2. Download the javadoc artifact from the repository and copy it to
*docsdir*.
3. Unzip it in *docsdir*.
- 4. Do svn add on *docsdir*.
- 5. Edit xdocs/javadoc.xml and add links to the new javadoc.
-6. Build and test. Follow the instructions in site/HOWTO to push the
- site changes to the Apache web site.
+ 4. Do `git add` on *docsdir*.
+ 5. Edit db-jdo-site/src/main/asciidoc/javadoc.adoc and add links to the new javadoc.
+6. Build and test. Follow the instructions in [db-jdo-site/README.md](https://github.com/apache/db-jdo-site/blob/master/README.md)
+ to push the site changes to the Apache web site.
<span id="postrelease"></span>
@@ -283,8 +282,7 @@
number. For example, create a branch named 2.1.1, from the 2.1
branch.
2. Merge bug fixes or other modifications into the new branch.
-3. In the new branch, modify trunk/README.txt to include a section on
- bug fixes since the 2.1 release, and to suggest checking out the
+3. In the new branch, modify README.md to include a section on
+ bug fixes since the previous release, and to suggest checking out the
source from a bug-fix branch to get the fixes listed.
-4. Link to this README in the web interface to svn from the .cgi
- download page and from http://db.apache.org/jdo/tck.html.
+4. Link to this README in the download page of the release.
