This page is to help a Lucene/Solr committer create a new release (you need committer rights for some of the steps to create an official release). It does not reflect official release policy - many of the items may be optional, or may be modified as necessary.

Release Process

With the release of Lucene Java 2.2.0 a new release process was established. Prior to every major release a feature freeze phase takes place for about 1-2 weeks. At the beginning of the feature freeze the trunk is branched and no commits other than serious bug fixes, documentation or build updates are permitted. This period of time should be used for extensive testing, documentation improvements and for cleaning up old JIRA issues.

Prerequisites

  1. (Optional) Edit your gnupg/gpg.conf file and add a default-key value with your Code Signing Key (as a HEX value) otherwise you may need to specify -Dgpg.key= later for signing. Make sure it is your 4K-bit key and not a 1K-bit key (esp. for ASF old timers)

  2. If you wish to have the stage target automatically copy the candidates to people.apache.org (which it does by default unless you specify -Dno.remote.copy=true), you will need the Ant optional library dependencies (see http://ant.apache.org/manual/install.html#librarydependencies) for sshexec and scp. Place them in your ant/lib or $HOME/.ant/lib.

  3. You may need to setup people.apache.org as a known host for ssh if you haven't already.

Planning

On dev@lucene.apache.org , decide on

  1. which JIRA issues shall be committed before a release is made; set the appropriate "Fix Version" in JIRA for these issues
  2. the date for branching the trunk and the start of the feature freeze phase
  3. the length of the feature freeze phase
  4. a tentative release date

Branching & Feature Freeze

  1. Run Apache RAT ("ant rat-sources", once you've installed the RAT jars on your CLASSPATH or ant -lib path) and fix any problems.
  2. If this is the first release in a series (i.e. release X.Y.0), then create a branch for the series: 
    svn copy https://svn.apache.org/repos/asf/lucene/dev/trunk \
https://svn.apache.org/repos/asf/lucene/dev/branches/lucene_solr_X_Y -m "Starting Lucene/Solr X.Y branch."
  3. After branching the new release series, update the default version in lucene/common-build.xml on trunk to X.Y+1-SNAPSHOT as well as tests.luceneMatchVersion to X.Y+1. Also update the LUCENE_MAIN_VERSION in src/java/org/apache/lucene/util/Constants.java. Also add the new enum constant into src/java/org/apache/lucene/util/Version.java. Update src/test-framework/java/org/apache/lucene/util/LuceneTestCase.java to use the current version.
  4. Prepare the backwards-compatibility tests in trunk (only if a new major release was started and you created the branch before): 
    svn rm backwards/src/
svn cp https://svn.apache.org/repos/asf/lucene/dev/branches/lucene_solr_X_Y/lucene/src/ backwards/src/
ant test-backwards

  5. On trunk, fix src/site/src/documentation/content/xdocs/tabs.xml to reference the X.Y+1-SNAPSHOT version. Rebuild the website (http://wiki.apache.org/lucene-java/HowToUpdateTheWebsite) and commit.

  6. On the branch, fix the same files, rebuild the website and commit.
  7. Send a note to dev@ to inform the committers that the branch has been created and the feature freeze phase has started. Include Do's and Don'ts for the feature freeze phase:
    • No new features may be committed to the branch.
    • Documentation patches, build patches and serious bug fixes may be committed to the branch. However, you should submit *all* patches you want to commit to Jira first to give others the chance to review and possibly vote against the patch. Keep in mind that it is our main intention to keep the branch as stable as possible.
    • All patches that are intended for the branch should first be committed to trunk and then merged into the branch.
    • Normal trunk development may continue as usual. However, if you plan to commit a big change to the trunk while the branch feature freeze is in effect, think twice: can't the addition wait a couple more days? Merges of bug fixes into the branch may become more difficult.
    • *Only* Jira issues with Fix version "X.Y" and priority "Blocker" will delay a release candidate build.

Release Workflow

  1. Check out the branch with: svn co https://svn.apache.org/repos/asf/lucene/dev/branches/lucene_solr_X_Y

  2. If the release is < 3.0, ensure "ant test-core" passes in a 1.4 Java environment. Important: Do two tests: Compile & test with Java 1.4, but also compile with Java 5 and only run tests with 1.4. This ensures, that the artifacts are really working with Java 1.4 (see the comment https://issues.apache.org/jira/browse/LUCENE-2285?focusedCommentId=12839224&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_12839224 for explanation).

  3. Build the code and javadocs, and run the unit tests: ant clean javadocs test
  4. Examine the results. Did it build without errors? Were there Javadoc warnings? Did the tests succeed? Does the demo application work correctly? Does Test2BTerms pass?
  5. Remove contrib/benchmark/{work,temp} if present
  6. Build as defined below in the "Building the Release Artifacts" section.
  7. If during the feature freeze phase bug fixes are committed to the X.Y branch then build another release candidate and announce on dev@ and java-user@ that everyone should use the new RC for testing.

  8. Call a release vote on dev@ and cc general@lucene.apache.org .

Building the Release artifacts

  1. If after the last day of the feature freeze phase no blocking issues are in JIRA with "Fix Version" X.Y then it's time to build the release artifacts
  2. Verify that "svnversion" reports a single revision with no modified changes
  3. Remove contrib/benchmark/{work,temp} if present

  4. Build the release artifacts: ant -Dversion=X.Y.Z [-Dgpg.exe=/path/to/gpg -Dgpg.key=YourKeyID -Dgpg.passphrase=YourPassPhrase] prepare-release  //Items in [] may be optional

  5. Sanity check the overall size of each artifact. EG, compare to the last release.
  6. Make sure that for each release file an md5 checksum file exists.
  7. ant -Dversion=X.Y.Z copy-to-stage to move the artifacts up to the staging area (see the build target for all the options for securly copying the artifacts up)

Example for 3.1

     >ant -Dversion=3.1.0 -Dgpg.key=FE045966 prepare-release
     // Inspect the artifacts
     >ant -Dversion=3.1.0 -Drc=rc3 -Dscp.user=gsingers copy-to-stage

Testing the Release artifacts

  1. There is a script in SVN to do automated checks on a release candidate, e.g python dev-tools/scripts/smokeTestRelease.py http://people.apache.org/~whoever/3.7.0rc1 3.7.0 tmp

Publishing

Once three PMC members have voted for a release, it may be published.

  1. Tag the release: 
    svn copy https://svn.apache.org/repos/asf/lucene/dev/branches/lucene_solr_X_Y \
https://svn.apache.org/repos/asf/lucene/java/tags/lucene_solr_X_Y_Z -m "Lucene Java X.Y.Z release."
  2. If this is a new branch (ie you are releasing X.Y.0), after tagging, commit a new "unreleased" section at the top of CHANGES.txt and contrib/CHANGES.txt onto the branch

  3. If this is your first release, add your key to the KEYS file. The KEYS file is located in Subversion at [WWW] https://svn.apache.org/repos/asf/lucene/java/dist and copy it to the release directory. Make sure you commit your change.

  4. If this is a point release, copy the CHANGES.txt entry for this point release back to the trunk's CHANGES.txt. Remove any duplicate entries from trunk's CHANGES.txt (ie, each issue should appear only once, in the earliest point-release that contains the fix, on the assumption that all future releases also contain the fix).

  5. See Guide To Distributing Existing Releases Through The ASF Mirrors and the links that are there.

  6. Copy the KEYS file, and the non-Maven release artifacts to the dist directory people.apache.org:/www/www.apache.org/dist/lucene/java, and remove the old files

  7. Make sure the group ownership on the site is 'lucene' by calling chgrp -R lucene /www/www.apache.org/dist/lucene/java. Also make files group writable and others read-only by calling chmod -R g+w,o-w /www/www.apache.org/dist/lucene/java

  8. Copy the Maven artifacts to the distribution directory (follow the existing directory structure), to have them pushed to the central Maven repositories: people.apache.org:/www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/lucene

  9. Make sure the group ownership on the site is 'committers' by calling chgrp -R lucene /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/lucene. Also make files group writable and others read-only by calling chmod -R g+w,o-w /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/lucene

  10. Checkout https://svn.apache.org/repos/asf/lucene/dev/nightly and update VERSION=X.Y-$BUILD_ID and MAVEN_ARTIFACT_VERSION in all the shell files. See http://wiki.apache.org/general/Hudson for how to get a login on Jenkins (formerly Hudson), or ask Grant or Michael B. for help.

  11. Wait 24 hours to give the mirrors a chance to get the new release.

Pushing website changes & Announcing

/!\ needs heavy updating to reflect new CMS based website /!\

/!\ BEGIN this info is all out of date /!\

  1. Checkout the top-level Lucene website from https://svn.apache.org/repos/asf/lucene/site. Add a new item under "News", in index.xml. Run "forrest site", confirm all looks good, then recursively copy build/site/* to publish/*, then commit the changes. Then copy publish/* to /www/lucene.apache.org/* on people.apache.org. Be sure to change the group and attributes of the copied files: cd /www/lucene.apache.org/; chgrp -R lucene * ; chmod -R ug+w,o-w *.

  2. Checkout the unversioned Lucene java website from https://svn.apache.org/repos/asf/lucene/java/site. Add a new item under "Lucene News", in index.xml. Add a new entry for this release into both tabs.xml and site.xml. Run "forrest site", confirm all looks good, and recursively copy build/site/* to docs/*, then commit the changes. Copy docs/* to /www/lucene.apache.org/java/docs/ on people.apache.org. Make sure .htaccess is copied!

  3. Copy the release specific docs from the binary release package to people.apache.org: 
      ssh people.apache.org
  tar xzf lucene-X.Y.Z.tar.gz lucene-X.Y.Z/docs
  mv lucene-X.Y.Z/docs /www/lucene.apache.org/java/X_Y_Z
  rmdir lucene-X.Y.Z

  4. Make sure the group ownership on the site is 'lucene' by calling chgrp -R lucene /www/lucene.apache.org/java. Also make files group writable and others read-only by calling chmod -R ug+w,o-w /www/lucene.apache.org/java.

/!\ END this info is all out of date /!\

  1. update the core & solr doap.rdf files to reflect the new versions using the Apache CMS

  2. Wait for these changes to appear on Apache's main webserver (http://lucene.apache.org) before doing the next steps (see http://www.apache.org/dev/project-site.html for details on how the site is mirrored to Apache's main web servers). Once they appear, verify all links are correct in your changes!

  3. Add the new version to Wikipedia (english and maybe your own language)

  4. Announce the release on general@lucene.apache.org , dev@lucene.apache.org , java-user@lucene.apache.org and announce@apache.org mailing lists. A draft should be sent to the development list first to clarify any possible issues in the announcement. Make sure the announcement has a brief blurb at the top saying what Lucene is (it will save you several snarky comments in reply.) Mails to the announce list should be sent from an @apache.org email address and contain a signature. Release announcements can be shared/edited in https://svn.apache.org/repos/asf/lucene/dev/misc/announcements.

  5. Ensure the latest Lucene Jar + MD5 sum file have been pushed to http://repo1.maven.org/maven2/org/apache/lucene/ by deploying the distribution to http://people.apache.org/repo/m2-ibiblio-rsync-repository/ (that is minotaur.apache.org:/www/people.apache.org/repo/m2-ibiblio-rsync-repository). From there it will be pushed to the Maven central repository automatically in a few hours. Contact repository@apache.org if there's some problem.

  6. Go to the JIRA "Manage Versions" Administration page (http://issues.apache.org/jira/secure/project/ManageVersions.jspa?pid=12310110) and click Release for the version you just released. Also add a new (unreleased) version for the next release on the trunk (for a major release) or branch (for a minor release).

  7. Go to JIRA and find all issues that were fixed in the release you just made, whose Status is Resolved, and do a bulk change to close all of these issues. Uncheck the box that says "send an email for these changes".

See Also

ReleaseTodo (last edited 2012-02-07 21:01:17 by HossMan)