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

 // A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required.

 *Step 1: Update extpaths.txt in CMS Staging*

 . Checkout CMS trunk:
 +
 [source,bash]
 $ 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.
 . `$ cd website-source` (where you just checked out the repo)
 . Add the path for the new Guide version:
 +
 [source,bash]
 $ echo solr/guide/X_Y >> extpaths.txt
 +
 where `X_Y` is the new version (i.e, `7_7`)
 . Commit changes:
 +
 [source,bash]
 $ 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:

 [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/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,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 production repo:
 +
 [source,bash]
 $ 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/.`
 . 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 New HTML Version the Default

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

 TIP: 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.mdtext` in SVN) to link to the newest version.
 . 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.
 +
 [source,text]
 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.).
	= 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 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

	// A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required.

	Step 1: Update extpaths.txt in CMS Staging

	. Checkout CMS trunk:
	+
	[source,bash]
	$ 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.
	. `$ cd website-source` (where you just checked out the repo)
	. Add the path for the new Guide version:
	+
	[source,bash]
	$ echo solr/guide/X_Y >> extpaths.txt
	+
	where `X_Y` is the new version (i.e, `7_7`)
	. Commit changes:
	+
	[source,bash]
	$ 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:

	[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/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,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 production repo:
	+
	[source,bash]
	$ 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/.`
	. 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 New HTML Version the Default

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

	TIP: 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.mdtext` in SVN) to link to the newest version.
	. 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.
	+
	[source,text]
	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.).