= Ref Guide Publication Process
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

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.

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

NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[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:

. Navigate to `./solr/solr-ref-guide`, where the Guide's `build.xml` is located.
. Run:
+
[source,bash]
$ 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.
. 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.

[source,bash]
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,pre-requisites>> from above.

[source,bash]
$ant clean default -Dsolr-guide-version=X.Y

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

IMPORTANT: 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*

. Checkout the directory you need to update from the svn production repo:
+
[source,bash]
$ 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_.
. 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/.`
. 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.
. 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 a link to the new Version from website

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*

. Look at https://lucene.staged.apache.org/solr/guide and see if the RM already has updated it. If not, continue
. 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.
. 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:

. Make a new pull request from https://github.com/apache/lucene-site/compare/production%2E%2E%2Emaster
. Note: If there are other changes staged, you will see those as well if you merge `master` into `production`
. 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.