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 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

Step 1: Update extpaths.txt in CMS Staging

  1. Checkout CMS trunk:

    $ svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source
    • If you already have this repo checked out, you can simply svn up website-source to update to the latest revision.
  2. $ cd website-source (where you just checked out the repo)

  3. Add the path for the new Guide version:

    $ echo solr/guide/X_Y >> extpaths.txt

    where X_Y is the new version (i.e, 7_7)

  4. Commit changes:

    $ svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt

Step 2: Push Guide to Website Production

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

You must push it to the path you just added to extpaths.txt, so if the path you added was solr/guide/7_7, you’ll use the path as shown in the below example:

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

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

Step 3: Push Staging extpaths.txt to Production

The extpaths.txt works by listing paths that should be ignored when the CMS syncs the staging and production repositories. Publishing staging to production will only succeed if the paths listed in extpaths.txt exist in production. At the same time, if a path exists in production but not in staging it will be deleted unless it is defined in extpaths.txt.

After pushing the content to production, check that the extpaths.txt in production includes the proper path to ensure that the Guide is not deleted incorrectly. If it does not exist in production, try to publish the site again to make sure it is updated.

Production URL: https://lucene.apache.org/extpaths.txt

Publish the 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 published, you need to update the production website repository and overwrite the existing files:

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 production repo:

    $ svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/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).

Make New HTML Version the Default

There are a few steps to take to make the new HTML version the default.

You can use the CMS system for these changes, or you can edit the file locally and commit it to the staging repo.
  1. Update the landing page at https://lucene.apache.org/solr/guide (the file is at content/solr/guide/index.mdtext in SVN) to link to the newest version.

  2. Update the Guide redirect rule that looks like the below in content/.htaccess so URLs without a version in the path are redirected to the latest available version.

    RedirectMatch temp /solr/guide/(?!index.html)([a-z].*) /solr/guide/7_7/$1

    In the above example, you would change the 7_7 part of the path to the right version (8_0, etc.).