Ref Guide Publication Process

This section details how to build the Guide for publication.

Guide Publication Overview

  1. Build and publish the DRAFT version.
  2. Continue to update docs as needed while Lucene/Solr artifact VOTE thread is ongoing.
  3. After VOTE has passed, build and publish final version to overwrite DRAFT watermarked pages.

Pre-Requisites

In order to build the Ref Guide, you must have the following:

  • You have checked out the Lucene/Solr source code on the machine you will be doing the release from.

  • You have Subversion installed. This is needed for committing the HTML files to the production website repo.

  • You have installed Ruby and several gems described in the README file located at solr/solr-ref-guide/README.adoc in your Lucene/Solr checkout.

  • All builds must be done from the release branch the Guide is for.

Builds are available via Jenkins for several branches. However, these HTML pages will have the DRAFT status noted in them and are not suitable for final production publishing.

Build the DRAFT Guide

The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined.

To build the HTML:

  1. Navigate to ./solr/solr-ref-guide, where the Guide’s build.xml is located.

  2. Run:

    $ ant clean default

    This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section Publish the Final Guide for steps to produce final production-ready HTML pages.

  3. The resulting Guide will be in solr/build/solr-ref-guide. The HTML files themselves will be in solr/build/solr-ref-guide/html-site.

Upload to the Website

Push the Guide directly to production via Subversion import from where you built it.

svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/sites/solr/guide/7_7

Confirm you can browse to Guide manually by going to the new URL. For example: https://solr.apache.org/guide/7_7

Publish the Final Guide

There are two steps to publishing the Guide: first, uploading the DRAFT pages with the production-ready version; and second, updating links to point to the new Guide.

Update DRAFT for Release

Since the Guide has already been uploaded to SVN, you need to overwrite the existing files in svn with a version of the production version of the guide:

Build Production Guide

Build the Guide locally with a parameter for the Guide version. This requires the same pre-requisites from above.

$ant clean default -Dsolr-guide-version=X.Y

where X.Y is the version you want to publish (i.e., 7.7).

The -Dsolr-guide-version system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the lucene/version.properties file in the current branch and assumes this is a DRAFT build which will have a DRAFT watermark and other labels on the pages. Including the -Dsolr-guide-version system property ensures the DRAFT watermark and labels are removed from the HTML files.

Pull Production Repo and Upload New Files

  1. Checkout the directory you need to update from the svn production repo:

    $ svn co https://svn.apache.org/repos/infra/sites/solr/guide/<dir>

    • This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.

    • Don’t shortcut this and download the whole production website. It will take an incredibly long time and that will feel like forever.

  2. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we’d do cp -r ./solr/build/solr-ref-guide/html-site 7_7/.
  3. Use svn status to see the files modified. If there are any pages added or deleted, use svn add <file> or svn rm <file> as needed.
  4. Commit the changes: svn commit -m "Update production 7.7 Ref Guide"

Verify Upload Successful

Spot-check a few pages to verify that the DRAFT watermark is gone, and also that Solr Javadocs link back to Lucene’s correctly (the UpdateRequestProcessor page has a lot of Javadoc links).

The only edit we need to do in the website itself is adding a link to the latest guide to /solr/guide.

Edit guide.md in staging

  1. Look at https://lucene.staged.apache.org/solr/guide and see if the RM already has updated it. If not, continue
  2. You can check out and push changes or edit the file directly in GitHub: https://github.com/apache/lucene-site/blob/master/content/pages/solr/guide.md by clicking the edit button and then adding a commit message.
  3. Verify that the staged version looks good (the link will not work in staging though)

Publish the changes to production

You can use your favourite git client to merge master into branch production. Or you can use GitHub website:

  1. Make a new pull request from https://github.com/apache/lucene-site/compare/production%2E%2E%2Emaster
  2. Note: If there are other changes staged, you will see those as well if you merge master into production
  3. Click the "Merge" button on the PR

The ordinary Solr release process will update the LUCENE_LATEST_RELEASE property of the website, which will ensure that Ref Guide URLs without a version in the path (e.g., /solr/guide/mypage.adoc) will automatically redirect to the latest Guide.