lucene-solr:branch_7x: Ref Guide: Update release steps to publish the Guide; increase TOC level so more sections appear in how-to-contribute page online

[ct...@apache.org]

Repository: lucene-solr
Updated Branches:
  refs/heads/branch_7x ebcf7c7ac -> f9df619c6


Ref Guide: Update release steps to publish the Guide; increase TOC level so more sections appear in how-to-contribute page online


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/f9df619c
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/f9df619c
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/f9df619c

Branch: refs/heads/branch_7x
Commit: f9df619c6427667cdf2b7fe1b28e6d49ff8267c2
Parents: ebcf7c7
Author: Cassandra Targett <ct...@apache.org>
Authored: Thu Nov 2 14:45:11 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Thu Nov 2 14:46:28 2017 -0500

----------------------------------------------------------------------
 solr/solr-ref-guide/src/how-to-contribute.adoc |  4 +--
 solr/solr-ref-guide/src/meta-docs/publish.adoc | 39 +++++++++++++++++----
 2 files changed, 34 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/f9df619c/solr/solr-ref-guide/src/how-to-contribute.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/how-to-contribute.adoc b/solr/solr-ref-guide/src/how-to-contribute.adoc
index 0116b66..7d4485b 100644
--- a/solr/solr-ref-guide/src/how-to-contribute.adoc
+++ b/solr/solr-ref-guide/src/how-to-contribute.adoc
@@ -1,6 +1,6 @@
 = How to Contribute to Solr Documentation
 :page-tocclass: right
-:page-toclevels: 2
+:page-toclevels: 3
 // 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
@@ -46,5 +46,5 @@ include::meta-docs/jekyll.adoc[leveloffset=+2]
 include::meta-docs/pdf.adoc[leveloffset=+2]
 
 == Building & Publishing the Guide
-include::meta-docs/publish.adoc[leveloffset=+2]
+include::meta-docs/publish.adoc[leveloffset=+1]
 endif::[]

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/f9df619c/solr/solr-ref-guide/src/meta-docs/publish.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/meta-docs/publish.adoc b/solr/solr-ref-guide/src/meta-docs/publish.adoc
index 5476fc3..d97754e 100644
--- a/solr/solr-ref-guide/src/meta-docs/publish.adoc
+++ b/solr/solr-ref-guide/src/meta-docs/publish.adoc
@@ -1,4 +1,4 @@
-= Publication Process
+= Publication Steps for Each 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
@@ -92,7 +92,7 @@ Votes must be sent to the lucene-dev mailing list (`dev@lucene.apache.org`).
 . You can add your own +1 to the vote announcement email.
 . If there are issues that need to be resolved, you can start the process over, using RC1, RC2, etc., as needed.
 
-Ideally, the HTML version will also be available for voters to evaluate, see the section <<Publishing HTML Version>> below for details of how to do that.
+NOTE: Ideally, the HTML version will also be available for voters to evaluate. See the section <<Publishing HTML Version>> below for details of how to do that.
 
 === Publish to Production & Archive Old Versions
 
@@ -144,7 +144,24 @@ WARNING: You must send the announcement email from your @apache.org email addres
 
 Always use the link to the download redirector for the announcement, as it will automatically direct users to the closest mirror for download: `https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf`.
 
-You could also include a link to the HTML version in your announcement, if the publication process for that has finished.
+You should include a link to the HTML version in your announcement. There are additional steps to modify the website for the HTML version, so see <<Release Steps for HTML Version>> below for details.
+
+.Sample announcement
+[source,text]
+----
+The Lucene PMC is pleased to announce that the Solr Reference Guide
+for 7.0 is now available.
+
+This 1,035-page PDF is the definitive guide to using Apache Solr, the
+search server built on Lucene.
+
+The PDF Guide can be downloaded from:
+https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-7.0.pdf.
+
+It is also available online at https://lucene.apache.org/solr/guide/7_0.
+----
+
+If the Guide is being published more than a day or two after the application itself, you should update the Solr website news page with the announcement (https://lucene.apache.org/solr/news.html).
 
 == Publishing HTML Version
 The steps to publish the Guide differ depending on if it is the first time the Guide has been published or if it is an update to an already published Guide.
@@ -192,13 +209,21 @@ The `extpaths.txt` works by listing paths that should be ignored when the CMS sy
 
 Production URL: https://lucene.apache.org/extpaths.txt
 
-==== Update Ref Guide Landing Page
+=== Release Steps for HTML Version
+
+When the PDF is announced as available, the HTML version should already be available on the Solr website. There are a few steps to take to make the new HTML version the default.
 
-Update the landing page at https://lucene.apache.org/solr/guide to link to the newest version.
+TIP: You can use the CMS system for these changes, or you can edit the file locally and commit it to the staging repo.
 
-You can use the CMS system for this since it is a small change, 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_0/$1
++
+In the above example, you would change the `7_0` part of the path to the right version (`7_1`, etc.).
 
-=== Update a Published Guide
+=== Updating Files in an Already-Published Guide
 
 If you need to re-publish an existing online copy of the Guide, you will need to checkout the directory in production website repository and overwrite the existing files: