HowToRelease

This page is prepared for Solr committers. You need committer rights to create a new Solr release.

1. Release Planning
2. Code Freeze
3. Steps For Release Engineer
   1. Before building release
   2. Making a release
   3. Post Release
4. Related Resources
5. :TODO: Things To Cleanup in this document

Release Planning

Start a discussion on solr-dev about having a release, questions to bring up...

• Any unresolved Jira issues with the upcoming version number listed as the "Fix Version"

• Any "Fixed" Jira issues missing a "Fix Version" that should be updated to indicate that there were fixed in this upcoming version

• Does any documentation needs an updated? Any necessary notes on upgrading for CHANGES.txt?

• Who is going to be the "release engineer" ?

• What day should be targeted for the release ? (leave buffer time for a code freeze and release candidate testing; make sure at least a few people commit to having time to help test the release candidates around the target date.)

Code Freeze

For 7-14 days prior to the release target date, have a "code freeze" where committers agree to only commit things if they:

• Are documentation improvements (including fixes to eliminate Javadoc warnings)

• Are new test cases that improve test coverage

• Are bug fixes found because of improved test coverage

• Are new tests and bug fixes for new bugs encountered by manually testing

Steps For Release Engineer

Before building release

1. Check that Solr works on the latest versions of Jetty, Tomcat, and Resin.

2. Double Check that there are no remaining unresolved Jira issues with the upcoming version number listed as the "Fix" version

3. Double Check that there are no "Fixed" Jira issues missing a "Fix Version" that should be marked as fixed in this release.

4. Make sure the src/maven artifact templates are in sync with the dependencies in the Ant build file.

5. Make sure the Ant sign-artifacts target is in sync with all of the artifacts that are created. All released artifacts must be signed.

Making a release

1. Run RAT ( http://incubator.apache.org/rat/) on the source. ant rat-sources. See https://issues.apache.org/jira/browse/SOLR-762.

2. Check if documentation needs an update, update release date in CHANGES.txt and add any necessary notes on upgrading.

3. Update news in src/site/src/documentation/content/xdocs/index.xml and for main lucene.apache.org site stored at https://svn.apache.org/repos/asf/lucene/site/. The second change may require additional rights or patch submitted to the Lucene PMC

4. Commit these changes.

   • Note: It is important to do this prior to the build so that it is reflected in the copy of the website included with the release for documentation purposes.

5. If this is the first release in a series (i.e. relase X.Y.0):

   1. create a branch for the series:

      svn copy https://svn.apache.org/repos/asf/lucene/solr/trunk \
        https://svn.apache.org/repos/asf/lucene/solr/branches/branch-X.Y -m "Starting Solr X.Y branch." 
      

   2. Create a new distribution directory: people.apache.org:/www/www.apache.org/dist/lucene/solr/X.Y

6. Check out the branch with: svn co https://svn.apache.org/repos/asf/lucene/solr/branches/branch-X.Y \

   • Note: at the moment releases need to be done on a unix box or in a cygwin environment with unix linefeeds, because fixcrlf is only done on the sources in the zip artifact

7. Update the version numbers in common-build.xml:

   • specversion should be set to X.Y.M.${dateversion}, where X.Y.M is the release being made.

   • version should be set to X.Y.N-dev, where N is one greater than the release being made.

   • maven_version should be the same as version for release but set to X.Y-SNAPSHOT for non-release.

8. Compile the code and run unit tests.

   • ant -Dversion=X.Y.M -Dspecversion=X.Y.M clean test

9. Regenerate the "site" docs per Website Update HOWTO so the documentation included with this release will reflect the correct version number (at the moment, this is specific to the tutorial)

10. Commit the build.xml and documentation changes from the previous few steps.

11. Build the release.

    • ant -Dversion=X.Y.M -Dspecversion=X.Y.M package

12. Check that release tgz/zip files looks ok - e.g. uncompress them, run example, work through the steps of the tutorial, ensure that the javadocs are readable, etc...

13. Sign the release (see Step-By-Step Guide to Mirroring Releases for more information).

    • gpg --armor --output dist/apache-solr-X.Y.M.tgz.asc --detach-sig dist/apache-solr-X.Y.M.tgz

    • gpg --armor --output dist/apache-solr-X.Y.M.zip.asc --detach-sig dist/apache-solr-X.Y.M.zip

    • :TODO: Sign the Maven artifacts. See https://issues.apache.org/jira/browse/SOLR-776

    • See the sign-artifacts target in the build.xml and the associated macrodefs in the common-build.xml file.

14. Produce one or more release candidates using the steps outlined here, up to the point of actually tagging the release and distributing it. Ask on solr-dev for reviewers of the release candidates. When a consensus emerges, build the final release candidate and call a vote. 3 +1 Lucene PMC votes are required for release (see voting). A Hudson job has been setup to help in creating and hosting Solr Release Candidates (named: "Solr Release Candidate"). Note the Hudson job does not do the signing required in the previous step, so the final release (at least) will need the signing step.

15. Now that you have read this, and done it at least once, know that there is an Ant target named prepare-release that takes care of much of this. You should still validate the docs, etc. and do the necessary checking. Calling prepare-release will call sign-artifacts. You will be prompted to enter you Code signing key numerous times, once per artifact that needs to be signed. This is a very important step.

16. :TODO: Hook in auto verification of signatures, figure out a way to enter the passphrase just once.

17. Tag the release:

    svn copy https://svn.apache.org/repos/asf/lucene/solr/branches/branch-X.Y \
       https://svn.apache.org/repos/asf/lucene/solr/tags/release-X.Y.M -m "Solr X.Y.M release."
    

18. Copy release files to the distribution directory.

    1. scp -p dist/apache-solr-X.Y.M.tar.gz* people.apache.org:/www/www.apache.org/dist/lucene/solr/X.Y

    2. scp -p dist/apache-solr-X.Y.M.zip* people.apache.org:/www/www.apache.org/dist/lucene/solr/X.Y

19. 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/solr

20. Ensure that the most current keys file is on the distribution site:

    • scp -p KEYS people.apache.org:/www/www.apache.org/dist/lucene/solr/

21. Start a new section in CHANGES.txt

22. Wait 24 hours for release to propagate to mirrors.

23. Add the new release info to the doap.rdf file, and double check for any other updates that should be made to the doap file as well if it hasn't been updated in a while. (Note: this file is used to power Solr's Listing on http://projects.apache.org/ as well as the Recent Apache Releases RSS feed)

24. Deploy new Solr site.

25. Deploy new main Lucene site.

26. Update Javadoc in people.apache.org:/www/lucene.apache.org/solr/docs/api.

    • NOTE: skip this for now, as this javadoc is currently updated automatically from the nightly build

27. Send announcements to the user and developer lists.

Post Release

• Housekeeping

  • Mark the version as "released" in Jira (noting the release date)

  • Create the next version in Jira (if it doesn't already exist)

• Publicity

  • update freshmeat (Yonik owns the project on Freshmeat, he may need to do this one)

  • TheServerSide blurb ( http://www.theserverside.com/news/post.tss)

  • blog away

• Documentation

  • Change wiki to match current best practices (remove/change deprecations, etc)

Related Resources

• http://www.apache.org/dev/#releases

• http://www.apache.org/dev/#mirror

:TODO: Things To Cleanup in this document

:TODO: