This section details how to build the Guide for publication.
Guide Publication Overview
Build and publish the DRAFT version.
Continue to update docs as needed while Lucene/Solr artifact VOTE thread is ongoing.
After VOTE has passed, build and publish final version to overwrite DRAFT watermarked pages.
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.adocin 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
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:
./solr/solr-ref-guide, where the Guide’s
$ 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.
The resulting Guide will be in
solr/build/solr-ref-guide. The HTML files themselves will be in
Upload to the Website
Step 1: Update extpaths.txt in CMS Staging
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-sourceto update to the latest revision.
$ cd website-source(where you just checked out the repo)
Add the path for the new Guide version:
$ echo solr/guide/X_Y >> extpaths.txt
X_Yis the new version (i.e,
$ 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
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
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
X.Y is the version you want to publish (i.e.,
Pull Production Repo and Upload New Files
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.
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/.
svn statusto see the files modified. If there are any pages added or deleted, use
svn add <file>or
svn rm <file>as needed.
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.|
Update the landing page at https://lucene.apache.org/solr/guide (the file is at
content/solr/guide/index.mdtextin SVN) to link to the newest version.
Update the Guide redirect rule that looks like the below in
content/.htaccessso 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_7part of the path to the right version (