solr/solr-ref-guide/src/meta-docs/publish.adoc - lucene-solr - Git at Google

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