Differences between revisions 30 and 31
Revision 30 as of 2014-02-26 17:18:16
Size: 18080
Editor: 98
Comment: Edit "Post-release JIRA admin tasks"
Revision 31 as of 2017-09-14 11:13:37
Size: 0
Comment: Content moved to https://github.com/ok2c/httpcomponents-release-tools/wiki
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
##language:en
#pragma section-numbers off
= HttpComponents Release Process =
== Preparations for using Nexus and uploading files ==
See MavenConfiguration for details on how to set up Maven. This only has to be done once.

== Release preparation ==
 * Make sure there are no open Jira issues targeted for this release
  * HttpCore - https://issues.apache.org/jira/browse/HTTPCORE
  * HttpClient - https://issues.apache.org/jira/browse/HTTPCLIENT
  * HttpAsyncClient - https://issues.apache.org/jira/browse/HTTPASYNC

 * Review RELEASE_NOTES.txt and make sure all important issues closed since the previous release are included in the release notes

 * Write an opening statement for the release highlighting the most changes, bug fixed and improvements

 * Make sure you are using the minimal JDK required by the release compatibility requirements and Maven 3.0.3

 * Maven 3.1.1 does not work (Error: Could not find or load main class org.codehaus.plexus.classworlds.launcher.Launcher)

 * Maven 3.0.5 works.

{{{
mvn -version
}}}
 * If this is a non-ALPHA release, verify binary compatibility with the previous stable baseline version. Baseline version is the latest stable xx.yy.00 release

{{{
mvn clirr:check
}}}
 . Please note Clirr currently can't handle Java 5 constructs very well and it can generate bogus errors about incompatibility of {{{Enum}}}s

{{{
[INFO] [clirr:check {execution: default-cli}]
[INFO] Comparing to version: 4.0
[ERROR] org.apache.http.impl.nio.reactor.SSLMode: Method 'public org.apache.http.impl.nio.reactor.SSLMode[] values()' is now final
[ERROR] org.apache.http.nio.reactor.IOReactorStatus: Method 'public org.apache.http.nio.reactor.IOReactorStatus[] values()' is now final
}}}
 * Generate release javadocs

{{{
mvn javadoc:aggregate
}}}
Make sure the command completes successfully and there are no warnings.

 * Generate tutorial if included in this release. Presently only HttpCore and HttpClient have tutorials.

{{{
mvn docbkx:generate-pdf docbkx:generate-html
}}}
Make sure the command completes successfully and there are no warnings.

== Release tools ==
 * Make a dedicated local copy of HttpCompoments release tools by checking out project source from the following location

https://svn.apache.org/repos/asf/httpcomponents/project-release-tools/trunk

{{{
svn co https://svn.apache.org/repos/asf/httpcomponents/project-release-tools/trunk release-httpcore-4.3.1
}}}
Given that a release can span across several days or even weeks it is recommended to have a dedicated copy of release tools per ongoing release process.

Release tools are basically a collection of Gradle scripts that simplify and facilitate time consuming, often tedious and therefore error-prone tasks.

 * Prepare gradle.properties

Make a copy of gradle.properties.template:

~-Linux-~

{{{
cp gradle.properties.template gradle.properties
}}}
~-Windows-~

{{{
copy gradle.properties.template gradle.properties
}}}
Edit gradle.properties file and update 'MAVEN_HOME', 'HC_DEV' and 'signing.*' properties

'MAVEN_HOME' must refer to the local Maven installation. You must set 'MAVEN_HOME' even if you have a 'MAVEN_HOME' environment variable.

~-Linux-~

{{{
MAVEN_HOME=opt/maven
signing.secretKeyRingFile=$HOME/.gnupg/secring.gpg
}}}
~-Windows-~

{{{
MAVEN_HOME=C:\\Java\\apache-maven-3.0.5
signing.secretKeyRingFile=C:/Users/ggregory/AppData/Roaming/gnupg/secring.gpg
}}}
'HC_DEV' must refer to the trunk or a stable branch of the project being releases, for example:

{{{
https://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/
https://svn.apache.org/repos/asf/httpcomponents/httpcore/branches/4.3.x/
}}}
Important: Check that you are using '''https''' and not '''http'''.

'signing.keyId' must contain id of the personal GPG key to be used for signing release artifacts.

'signing.secretKeyRingFile' must refer to the personal GPG ring file.

'signing.password' may be left empty. In this case the script will be prompting for a pass phrase every time access to the key is needed.

 * Make sure that the scripts are valid by listing available tasks

{{{
gradlew -q tasks
}}}
== Building release artifacts ==
 * Check out the latest snapshot from the release branch

{{{
gradlew -q checkoutSnapshot
}}}
 * Prepare release tag

{{{
gradlew -q prepareRelease
}}}
Manually enter release version or hit enter to select the default based on pom.xml content (current version sans -SNAPSHOT qualifier)

The task will print out the location of the release tag. Please double-check its validity.

{{{
Release tag to be created: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.3.1
}}}
 * Prepare RC tag

{{{
gradlew -q prepareRC
}}}
Manually enter RC qualifier or hit enter to select the default one (RC1)

The task will print out the location of the RC tag. Please double-check its validity.

{{{
RC tag to be created: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.3.1-RC1
}}}
Optionally run preview task to see what changes have been made to the current snapshot. The RC tag will be created by copying those changes to the tag location

{{{
gradlew -q previewRC
}}}
{{{
Local changes for https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.3.1-RC1
/home/oleg/src/apache.org/httpcomponents/release-httpcore-4.3.1/build/repos-asf-httpcomponents-httpcore-trunk
M httpcore-osgi/pom.xml
M httpcore-nio/pom.xml
M httpcore/pom.xml
M pom.xml
M httpcore-ab/pom.xml
}}}
 * Create RC tag

{{{
gradlew -q commitRC
}}}
 * Check out RC from the RC tag

{{{
gradlew -q checkoutRC
}}}
 * Build RC and install it to the local Maven repository

{{{
gradlew -q buildRC
}}}
This task will execute 'maven install site' as an external command. Make sure the task terminates successfully without any error.

 * If a gpg agent is present, deploy RC to the staging artifact repositor with:

{{{
gradlew -q deployRC
}}}
This task will execute 'maven -Prelease deploy' as an external command. Make sure the task terminates successfully without any error.

The 'release' profile parameter will cause release artifacts to be signed prior to deployment to Nexus where will be held in the staging repository until they are promoted or deleted.

The command assumes presence of a functional gpg setup and of a gpg agent on the local system.

 * If a gpg agent is ''not'' present, deploy RC to the staging artifact repositor with Maven manually:

{{{
gradlew -q locateRC
}}}
{{{
Please deploy HttpCore 4.3.1 based on RC1 from the following directory using 'mvn deploy -Prelease'
/home/oleg/src/apache.org/httpcomponents/project-release-tools/build/repos-asf-httpcomponents-httpcore-tags-4.3.1-RC1
}}}
Change to the RC location and execute 'mvn deploy -Prelease' passing additional parameters, if necessary, for example:

{{{
cd /home/oleg/src/apache.org/httpcomponents/project-release-tools/build/repos-asf-httpcomponents-httpcore-tags-4.3.1-RC1
mvn deploy -Prelease -Dgpg.passphrase=MySecret
}}}
Login to the ASF Nexus repository manager at the following location

https://repository.apache.org/index.html#welcome

 * Select 'Staging Repositories'
 * Mark release artifacts as 'Closed' in the Nexus artifact repository
  * Check that the correct files are present (e.g. binary, source, Javadoc), and "Close" the upload directory.
  * This will allow the files to be seen publicly, but the files won't be added to the Central Maven repo yet.
  * You can then delete any unwanted files (such as .asc.md5 and .asc.sha1) (N.B. You cannot delete files until the upload is closed).
  * Check that the files at the public URL look OK.
  * If not, you can delete them all and try again.

Important! The public URL, which will look something like https://repository.apache.org/content/repositories/orgapachehttpcomponents-nnn/, should be copied into the Release Vote e-mail (see below).

 * Check out staging dist repository

{{{
gradlew -q checkoutDistStage
}}}
 * Assemble release dist packages

{{{
gradlew -q assemble
}}}
The build script will prompt for key pass-phrase if the 'signing.password' parameter has been left empty in gradle.properties.

 * Prepare dist packages for import into the staging repository

{{{
gradlew -q prepareDist
}}}
Optionally run preview task to see what files have been scheduled for import into the staging repository.

{{{
gradlew -q previewDist
}}}
{{{
Local changes for release dist https://dist.apache.org/repos/dist/dev/httpcomponents/
/home/oleg/src/apache.org/httpcomponents/release-httpcore-4.3.1/build/repos-dist-dev-httpcomponents
A httpcore-4.3.1-RC1
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-osgi-bin.zip.md5
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-bin.zip
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-osgi-bin.tar.gz.md5
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-osgi-bin.zip
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-src.zip
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-bin.tar.gz
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-bin.tar.gz.md5
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-src.tar.gz.asc
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-bin.tar.gz.asc
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-osgi-bin.zip.asc
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-osgi-bin.tar.gz.asc
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-bin.zip.md5
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-src.tar.gz.md5
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-src.tar.gz
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-src.zip.md5
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-osgi-bin.tar.gz
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-bin.zip.asc
A httpcore-4.3.1-RC1/RELEASE_NOTES-4.3.x.txt
A httpcore-4.3.1-RC1/httpcomponents-core-4.3.1-src.zip.asc
}}}
 * Commit dist packages to the staging repository

{{{
gradlew -q commitDist
}}}
== Release vote ==
 * Prepare release vote content

{{{
gradlew -q prepareVote
}}}
This will generate output like the following:

{{{
----------------8<-------------[ cut here ]------------------
[VOTE] Release HttpComponents Core 4.3.1 based on RC1

Please vote on releasing these packages as HttpComponents Core 4.3.1.
The vote is open for the at least 72 hours, and only votes from
HttpComponents PMC members are binding. The vote passes if at least
three binding +1 votes are cast and there are more +1 than -1 votes.

Packages:
https://dist.apache.org/repos/dist/dev/httpcomponents/httpcore-4.3.1-RC1
revision 3948

Release notes:
https://dist.apache.org/repos/dist/dev/httpcomponents/httpcore-4.3.1-RC1/RELEASE_NOTES-4.3.x.txt

Maven artefacts:
[link]

SVN tag:
https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.3.1-RC1
revision 1551921

--------------------------------------------------------------------------
Vote: HttpComponents Core 4.3.1 release
[ ] +1 Release the packages as HttpComponents Core 4.3.1.
[ ] -1 I am against releasing the packages (must include a reason).
----------------8<-------------[ cut here ]------------------
}}}
 * Replace '[link]' with the Nexus URL from https://repository.apache.org
 * Call release vote on dev@hc.apache.org by sending the generated and edited text

== Release vote result ==
 * Tally votes after the voting deadline elapsed (usually 72 hours, but may be extended if not
  . enough votes have been cast)

=== If the vote fails ===
 * Cancel current RC

{{{
gradlew -q cancelRC
}}}
 . This command will invalidate local RC checkout and increment RC count. It will _not_ remove any staged artifacts or packages.

 * Login to Nexus and "Delete" the staged uploads

https://repository.apache.org/index.html#welcome

 * Address concerns / problems stated as reasons for negative votes in your normal development

environment

 * Update the local snapshot from the release branch to pull the latest changes

{{{
gradlew -q updateSnapshot
}}}
 * Restart the release process from the 'Prepare RC tag' section.

=== If the vote succeeds ===
 * Find the original original voting thread at

http://mail-archives.apache.org/mod_mbox/hc-dev/

 * Prepare vote result message using the following template

{{{
[VOTE][RESULT] HttpComponents Core 4.3.1 release

The vote to release HttpComponents Core 4.3.1 has passed with the following results

+1 (4 binding votes in total)
aaaa <aaaa -at- apache.org> *
bbbb <bbbb -at- apache.org>
cccc <cccc -at- apache.org> *
dddd <dddd -at- apache.org> *
eeee <eeee -at- apache.org> *

-1 (1 binding vote in total)

ffff <ffff -at- apache.org> *

* binding votes

Original voting thread:
[insert link here]
}}}
 * Send results to dev@hc.apache.org and private@hc.apache.org

 * Promote the current RC to official release

{{{
gradlew -q promoteRC
}}}
{{{
Promoting HttpCore 4.3.1 RC1 to official release
Copying https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.3.1-RC1 to https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.3.1
}}}
== Release deployment ==
 * Deploy release artifacts

Login to the Nexus repository, and "Release" the staging directory.

https://repository.apache.org/index.html#welcome

This will cause the artifacts to be released to the Central Maven repo.

 * Deploy dist packages

{{{
gradlew -q promoteDist
}}}
Alternatively if some customization of the process is required one may generate a svnmucc input file instead

{{{
gradlew -q svnmucc
}}}
== Prepare next development cycle ==
* Update project metadata in pom.xml files

{{{
gradlew -q prepareNextVersion
}}}
Manually enter next snapshot version or hit enter to select the default based on pom.xml content

Optionally run preview task to see what changes have been made to the current snapshot.

{{{
gradlew -q previewNextVersion
}}}
{{{
Next development version: 4.3.2-SNAPSHOT
/home/oleg/src/apache.org/httpcomponents/release-httpcore-4.3.1/build/repos-asf-httpcomponents-httpcore-trunk
M httpcore-osgi/pom.xml
M httpcore-nio/pom.xml
M httpcore/pom.xml
M pom.xml
M httpcore-ab/pom.xml
}}}
 * Commit updated project metadata

{{{
gradlew -q commitNextVersion
}}}
== Update project website site ==
=== Update website source ===
Project website source can be found here

http://svn.apache.org/repos/asf/httpcomponents/project-website/trunk/

 * Review and update News, Status, Download pages

 * Check that the ApacheCon advert in the css file is for the appropriate date

{{{
src/site/apt/news.apt
src/site/apt/status.apt
src/site/resources/css/hc-maven.css
src/site/xdoc/downloads.xml
}}}
=== Prepare local stage ===
 * Checkout the latest snapshot of the main website source and the released project

{{{
gradlew -q checkoutFullWebsite
}}}
 * Render website content

{{{
gradlew -q generateFullWebSite
}}}
You may get an error here if the parent POM is not present because the project uses a SNAPSHOT version. You can checkout the project trunk (for example 8-SNAPSHOT) at http://svn.apache.org/repos/asf/httpcomponents/project/trunk/ and install it locally by running 'mvn install -N'.

You can at any time pick up the latest changes from the repository by running

{{{
gradlew -q updateMainWebSite generateFullWebSite
}}}
 * Prepare project site stage

{{{
gradlew -q checkoutSiteStage
}}}
 * Stage updated website content

{{{
gradlew -q siteStage
}}}
 * Preview staged website content

{{{
gradlew -q previewSiteStage
}}}
{{{
Local changes for project website
/home/oleg/src/apache.org/httpcomponents/release-httpcore-4.3.1/build/repos-asf-httpcomponents-site
...
}}}
You can now use a browser to review the content located in the staging directory.

 * Commit staged website content

Once satisfied with the changes, commit local changes to the repository.

{{{
gradlew -q commitSiteStage
}}}
Enter commit message when promted

{{{
oleg@ubuntu:~/src/apache.org/httpcomponents/release-httpcore-4.3.1$ ./gradlew -q commitSiteStage
Please enter commit message:
...
}}}
== Announce release ==
 * Before sending out an announcement, check that the files are available through Maven (https://search.maven.org) and some mirrors. Waiting 24 hours gives the Maven repositories and mirrors a chance to distribute the files.
 * Send out an announcement to the following lists: announce@apache.org , private@hc.apache.org ,
  . dev@hc.apache.org , httpclient-users@hc.apache.org

{{{
[ANNOUNCEMENT] HttpComponents Core 4.3.1 Released

The Apache HttpComponents project is pleased to announce 4.3.1 GA release of HttpComponents Core.

[release specific content]

Download -
<http://hc.apache.org/downloads.cgi>
Release notes -
<http://www.apache.org/dist/httpcomponents/httpcore/RELEASE_NOTES.txt>
HttpComponents site -
<http://hc.apache.org/>

About HttpComponents Core

HttpCore is a set of low level HTTP transport components that can be used to build custom client and server side HTTP services with a minimal footprint. HttpCore supports two I/O models: a blocking I/O model based on the classic Java I/O and a non-blocking, event driven I/O model based on Java NIO.
}}}
== Post-release JIRA admin tasks ==
 * Update JIRA project data: Project -> Administer project -> Versions: Manage
  * HttpCore - https://issues.apache.org/jira/browse/HTTPCORE
  * HttpClient - https://issues.apache.org/jira/browse/HTTPCLIENT
  * HttpAsyncClient - https://issues.apache.org/jira/browse/HTTPASYNC

 * Mark current version as Released

 * This may also be a good moment to mark old unsupported release versions as Archived and to add new release targets

 * Delete old versions from https://www.us.apache.org/dist/httpcomponents/