You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2018/06/28 20:37:31 UTC
lucene-solr:branch_7x: SOLR-12529: clean up how to publish ref guide
docs
Repository: lucene-solr
Updated Branches:
refs/heads/branch_7x 154952f47 -> 4212da569
SOLR-12529: clean up how to publish ref guide docs
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/4212da56
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/4212da56
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/4212da56
Branch: refs/heads/branch_7x
Commit: 4212da569232624d803cece13f5f6b5d0695b30f
Parents: 154952f
Author: Cassandra Targett <ct...@apache.org>
Authored: Thu Jun 28 15:36:14 2018 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Thu Jun 28 15:37:24 2018 -0500
----------------------------------------------------------------------
solr/solr-ref-guide/src/how-to-contribute.adoc | 4 +-
solr/solr-ref-guide/src/meta-docs/jekyll.adoc | 4 +-
solr/solr-ref-guide/src/meta-docs/publish.adoc | 165 ++++++++++----------
3 files changed, 86 insertions(+), 87 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/4212da56/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 7d4485b..4a30dbe 100644
--- a/solr/solr-ref-guide/src/how-to-contribute.adoc
+++ b/solr/solr-ref-guide/src/how-to-contribute.adoc
@@ -38,13 +38,13 @@ include::meta-docs/asciidoc-syntax.adoc[leveloffset=+2]
include::meta-docs/editing-tools.adoc[leveloffset=+2]
-== Modifying the Output Formats
+== Modifying the Publication Formats
The Solr Reference Guide is published in two formats: HTML and PDF. Different tools are used for each.
include::meta-docs/jekyll.adoc[leveloffset=+2]
include::meta-docs/pdf.adoc[leveloffset=+2]
-== Building & Publishing the Guide
+// This is the how to publish section:
include::meta-docs/publish.adoc[leveloffset=+1]
endif::[]
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/4212da56/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/meta-docs/jekyll.adoc b/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
index 52b928f..0fba944 100644
--- a/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
+++ b/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
@@ -199,9 +199,7 @@ My content...
An Ant target `build-site` will build the full HTML site. This target builds the navigation for the left-hand menu, and converts all `.adoc` files to `.html`, including navigation and inter-document links.
-Building the HTML has several dependencies that will need to be installed on your local machine. Review the `README.txt` file in the `solr/solr-ref-guide` directory for specific details.
-
-See <<how-to-contribute.adoc#publishing-html-version,Publishing the HTML Version>> for more information about building.
+Building the HTML has several dependencies that will need to be installed on your local machine. Review the `README.adoc` file in the `solr/solr-ref-guide` directory for specific details.
=== Build Validation
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/4212da56/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 1ebbf63..78ef290 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 Steps for Each Process
+= 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
@@ -16,26 +16,34 @@
// specific language governing permissions and limitations
// under the License.
-== About the Formats
+The PDF version of the Guide is the *official* release, and requires a vote before release.
-The Solr Ref Guide is published in two formats: PDF and HTML.
+The HTML version is considered a "convenience" version, and does not require a vote.
-The PDF version is the *official* release, and requires a vote before release. See <<Publishing PDF Version>> for details on how to generate the PDF and hold a vote.
+It's strongly preferred that both PDF and HTML versions are available during the vote for the PDF. However, since the HTML version is not an official release, it is more of an unwritten rule to publish the HTML at the same time as producing a release candidate for the PDF.
-The HTML version is considered a "convenience" version, and does not require a vote. See <<Publishing HTML Version>> for details on how to publish the HTML.
+IMPORTANT: These instructions assume you have the proper dependencies for building HTML and are publishing both versions simultaneously. See <<Additional Pre-Requisites for HTML>> for details.
-It's strongly preferred that both PDF and HTML versions are available during the vote for the PDF. However, since the HTML version is not an official release, it is more of an unwritten rule to publish the HTML at the same time as producing a release candidate for the PDF.
+== Pre-Requisites
-== Publishing PDF Version
The PDF version of the Solr Reference Guide is the *official* version. As such, it is voted on by the community before release, and is treated as an official artifact of the Lucene/Solr project.
-=== Prerequisites
+=== Pre-Requisites for PDF
+
+The build process downloads the required .jar to build the PDF version, so the only pre-requisites are for the publication process:
* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. You will need scripts in the `dev-tools` directory.
* You have generated a GPG key. See the Apache documentation on https://www.apache.org/dev/release-signing.html#generate[generating a code signing key].
* You have Python 3 installed. This is needed to poll the mirrors after release to be sure it's propagated enough to make the announcement.
+* You have Subversion installed. This is needed for committing the PDF to `dist/dev` and `dist/releases` repos.
+
+=== Additional Pre-Requisites for HTML
-=== Generate the PDF
+To build the PDF locally, you need several required dependencies, listed in `solr-ref-guide/README.adoc`. If you do not have these dependencies locally, you cannot build and publish the Ref Guide.
+
+NOTE: Builds are available via Jenkins for several branches. However, these HTML pages will have the `DRAFT` status noted in them and will not be suitable for publishing.
+
+== Generate the PDF & HTML
No local dependencies are required to build the PDF. The Ant target will download the jars and other items it requires.
@@ -43,12 +51,14 @@ The build process generates the PDF, including the page hierarchy, and then runs
To build the PDF:
-. Run `ant build-pdf -Dsolr-guide-version=X.Y`
-. The resulting PDF will be in `solr/build/solr-ref-guide`.
+. Run `ant clean default -Dsolr-guide-version=X.Y`, where `X.Y` is the version you want to publish (i.e., `7.4`).
+. The resulting PDF will be in `solr/build/solr-ref-guide`. The HTML files will be in `solr/build/solr-ref-guide/html-site`.
+
+IMPORTANT: The `-Dsolr-guide-version` system property is optional. By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build. Including this system property ensures the DRAFT watermark and labels are removed from the HTML files.
-IMPORTANT: The `-Dsolr-guide-version` system property is optional. By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build.
+== Prepare & Upload Release Candidate
-=== Prepare and Upload Release Candidate
+=== Upload PDF to dist/dev
The `dist/dev` Subversion repository includes a directory for the Solr Ref Guide at https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/[`lucene/solr/ref-guide`] which can host the release candidate (RC) during the VOTE stage of the process.
@@ -86,7 +96,43 @@ user: "Your Name <yo...@apache.org>"
.. `svn add apache-solr-ref-guide-7.0-RC0`
.. `svn commit -m "7.0 ref guide RC0"`
-=== Hold a VOTE
+=== Upload HTML Files
+// 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`
+. Add Guide branch dir: `echo solr/guide/X_Y >> extpaths.txt`
+. 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
+
+Go to the checkout directory where you have built the Guide and push the documentation via subversion import. You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/6_5`, you'll use the path as shown in the below example:
+
+[source,bash]
+svn -m "Add Ref Guide for Solr 6.5" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/6_5
+
+Confirm you can browse to these URLs manually, and especially that Solr javadocs link back to lucene's correctly. Example:
+https://lucene.apache.org/solr/guide/6_5
+
+==== 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
+
+== Hold a VOTE
Votes must be sent to the lucene-dev mailing list (`dev@lucene.apache.org`).
. Send an email to `dev@lucene.apache.org` with subject, "VOTE: Release Apache Solr Ref Guide for Solr X.Y".
@@ -94,9 +140,11 @@ 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.
-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.
+NOTE: Ideally, the HTML version will also be available for voters to review.
-=== Publish to Production & Archive Old Versions
+== Publish the Guide
+
+=== Move the PDF to dist/releases
Once at least three PMC members have voted for release (see https://www.apache.org/foundation/voting.html#ReleaseVotes[Apache Voting Process] for details on the rules for votes), the release candidate can be released.
@@ -122,6 +170,8 @@ python3 -u ~/lucene-source/dev-tools/scripts/poll-mirrors.py -details -p lucene/
* This script requires Python 3 to be installed on your machine.
* If you have over 85% of the mirrors with the file, it's OK to go ahead with the announcement.
. You may get an automated email about updating the ASF release repository; you can safely ignore this email.
+
+=== Archive Old PDF Versions
. The `dist/releases` repo is only meant to keep the latest releases. Shortly after new releases are mirrored, they are copied to `archive.apache.org`, so older releases can safely be deleted from `dist/releases` since they have been backed up in the archives.
.. Run the Archive Ref Guide script (`archive-solr-ref-guide.sh`) using the X.Y version of the Ref Guide that has just been published. Older RCs will also be removed.
.. Again, this script doesn't do any direct removal of files, it only outputs SVN commands for you to copy and paste:
@@ -138,7 +188,21 @@ svn rm -m 'removing archived ref guide files prior to X.Y' https://dist.apache.o
svn rm -m 'cleaning up old RCs now that X.Y has been released' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC0/ https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC1/
----
-=== Announce the Release
+=== Make New HTML Version the Default
+
+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.
+
+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_0/$1
++
+In the above example, you would change the `7_0` part of the path to the right version (`7_1`, etc.).
+
+== Announce the Release
Announce the availability of the new Ref Guide on `solr-user@lucene.apache.org` and CC `general@lucene.apache.org` and `announce@apache.org`.
@@ -146,7 +210,7 @@ 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 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.
+You should include a link to the HTML version in your announcement.
.Sample announcement
[source,text]
@@ -165,67 +229,7 @@ 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.
-
-=== Building the HTML Version
-
-If you have the required dependencies on your local machine, you can build the HTML version with `ant build-site -Dsolr-guide-version=X.Y`. The dependencies are listed in `solr-ref-guide/README.adoc`.
-
-Tip::
-+
-//TODO update Jenkins link
-If you do not have the required dependencies, and don't choose to install them, you can download the files from the Jenkins (https://builds.apache.org/job/Solr-reference-guide-jira-SOLR-10290/lastSuccessfulBuild/artifact/solr/build/solr-ref-guide/html-site/[Solr Reference Guide job]). But these HTML pages will have the `DRAFT` status noted in them and will not be suitable for publishing.
-
-=== Publish a New Guide
-// 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`
-. Add Guide branch dir: `echo solr/guide/X_Y >> extpaths.txt`
-. 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
-
-Go to the checkout directory where you have built the Guide and push the documentation via subversion import. You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/6_5`, you'll use the path as shown in the below example:
-
-[source,bash]
-svn -m "Add Ref Guide for Solr 6.5" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/6_5
-
-Confirm you can browse to these URLs manually, and especially that Solr javadocs link back to lucene's correctly. Example:
-https://lucene.apache.org/solr/guide/6_5
-
-==== 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
-
-=== 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.
-
-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_0/$1
-+
-In the above example, you would change the `7_0` part of the path to the right version (`7_1`, etc.).
-
-=== Updating Files in an Already-Published Guide
+== Updating HTML Files after Publication
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:
@@ -237,6 +241,3 @@ If you need to re-publish an existing online copy of the Guide, you will need to
. 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 6.5 Ref Guide"`
-
-// TODO:
-// - figure out if redirects in .htaccess require any work here (probably)