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 2017/05/01 16:26:33 UTC
lucene-solr:jira/solr-10290: SOLR-10295: Add PDF instructions to
publish guide
Repository: lucene-solr
Updated Branches:
refs/heads/jira/solr-10290 e375e2500 -> 8b5f96933
SOLR-10295: Add PDF instructions to publish guide
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/8b5f9693
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/8b5f9693
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/8b5f9693
Branch: refs/heads/jira/solr-10290
Commit: 8b5f9693354b9019caf43c98badaf496ab9361e2
Parents: e375e25
Author: Cassandra Targett <ct...@apache.org>
Authored: Mon May 1 11:26:08 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Mon May 1 11:26:08 2017 -0500
----------------------------------------------------------------------
solr/solr-ref-guide/README.adoc | 4 +-
solr/solr-ref-guide/meta-docs/publish.adoc | 155 ++++++++++++++++++++++--
2 files changed, 150 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8b5f9693/solr/solr-ref-guide/README.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index fa06fec..80b99f6 100644
--- a/solr/solr-ref-guide/README.adoc
+++ b/solr/solr-ref-guide/README.adoc
@@ -7,12 +7,12 @@ Raw content is stored in Asciidoc (`.adoc`) formated files in the `src/` directo
These files are processed with AsciiDoctor in 2 different ways:
* Via 'Jekyll' to build an HTML browsable version of the Ref Guide
-** Prerequisites: `ruby` and the following gems must be installed:
+** Prerequisites: `Ruby` and the following gems must be installed:
*** `jekyll`
*** `jekyll-asciidoc`
*** `pygments.rb`
* Via `asciidoctor-ant` to build the officially released PDF version of the Ref Guide
-** Prerequisites: None (except for those required to use the Lucene/Solr build: Java, Ant)
+** Prerequisites: None (except for those required to use the Lucene/Solr build: Java, Ant)
For details on building the ref guide, see `ant -p`.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8b5f9693/solr/solr-ref-guide/meta-docs/publish.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/meta-docs/publish.adoc b/solr/solr-ref-guide/meta-docs/publish.adoc
index 7a88e93..25d288e 100644
--- a/solr/solr-ref-guide/meta-docs/publish.adoc
+++ b/solr/solr-ref-guide/meta-docs/publish.adoc
@@ -1,27 +1,168 @@
-= Publishing Process
+= Publication Process
:toc:
-// 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.
+== About the Formats
+
+The Solr Ref Guide is published in two formats: PDF and HTML.
+
+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.
+
+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.
+
+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.
+
+== 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.
+
+=== Generate the PDF
+
+No local dependencies are required to build the PDF. The Ant target will download the jars and other items it requires.
+
+The build process generates the PDF, including the page hierarchy, and then runs an optimization script on the PDF to make it smaller.
+
+To build the PDF:
+
+. Run `ant build-pdf`
+. The resulting PDF will be in `solr/build/solr-ref-guide`.
+
+=== Prerequisites
+
+* 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.
+
+=== Prepare and Upload Release Candidate
+
+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.
+
+These steps walk through checking out this directory and uploading the Guide to it.
+
+. Checkout the directory: `svn co https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide solr-ref-guide-rc`
+* If you have already checked out this directory, you can simply update it: `svn update solr-ref-guide-rc`
+. Change directories so `solr-ref-guide-rc` is your working directory (`cd solr-ref-guide-rc`).
+
+IMPORTANT: The next step requires that you have already generated your GPG keys. Your GPG passphrase will be required.
+
+[start=3]
+. Run the Prep Ref Guide script to prepare the RC. This script ensures proper naming of the PDF file, generates `.sha1` and `.asc` files and creates the proper RC sub-directories under `solr-ref-guide-rc`.
+.. The structure of the input is: `prep-solr-ref-guide-rc.sh <path/PDFfilename> <Solrversion-RC#> GPGkey`.
+.. From the `solr-ref-guide-rc` directory, it will look something like this:
++
+[source,bash]
+----
+$ ~/lucene-source/dev-tools/scripts/prep-solr-ref-guide-rc.sh apache-solr-ref-guide-7.0.pdf 7.0-RC0
+
++ mkdir apache-solr-ref-guide-7.0-RC0
++ mv apache-solr-ref-guide-7.0.pdf apache-solr-ref-guide-7.0-RC0/apache-solr-ref-guide-7.0.pdf
++ cd apache-solr-ref-guide-7.0-RC0
++ sha1sum apache-solr-ref-guide-7.0.pdf
++ gpg -u DEADBEEF --armor --output apache-solr-ref-guide-7.0.pdf.asc --detach-sig apache-solr-ref-guide-7.0.pdf
+
+You need a passphrase to unlock the secret key for
+user: "Your Name <yo...@apache.org>"
+4096-bit RSA key, ID DEADBEEF, created 1969-07-04
+----
++
+. Add and commit the new release candidate to the `dist/dev` with these steps:
+.. `svn add apache-solr-ref-guide-7.0-RC0`
+.. `svn commit -m "7.0 ref guide RC0"`
+
+=== 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".
+. The body of the email should include the full URL of the RC directory in the `dist/dev` repo. Such as: https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-7.0-RC0
+. 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.
+
+=== Publish to Production & Archive Old Versions
+
+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.
+
+. Use the Publish Solr Ref Guide script (`publish-solr-ref-guide.sh`) to generate the proper SVN commands to be run to execute a remote move of the RC files to the final `dist/releases` repository.
+.. The script takes only the version and _RC number that passed the vote_ as inputs, such as `7.0-RC0`.
+.. The input and output of the script will look like this:
++
+[source,bash]
+----
+$ ~/lucene-source/dev-tools/scripts/publish-solr-ref-guide-rc.sh X.Y-RCZ
+
+## Run the following commands when ready...
+svn move -m 'publishing apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.asc https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.sha1 https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/
+
+svn rm -m 'cleaning up apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ
+----
+[start=2]
+. The release should propagate to as many mirrors as possible before announcing the release, generally 24 hours is long enough. Use the Poll Mirrors script (`poll-mirrors.py`) to check the status:
++
+[source,bash]
+python3 -u ~/lucene-source/dev-tools/scripts/poll-mirrors.py -details -p lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf
+
+* 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.
+. 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:
++
+[source,bash]
+----
+$ ~/lucene-source/dev-tools/scripts/archive-solr-ref-guide.sh X.Y
+## Run the following commands when ready...
+
+# Delete old releases
+svn rm -m 'removing archived ref guide files prior to X.Y' https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.asc https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.sha1
+
+# Delete old RC files
+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
+
+Announce the availability of the new Ref Guide on `solr-user@lucene.apache.org` and CC `general@lucene.apache.org` and `announce@apache.org`.
+
+WARNING: You must send the announcement email from your @apache.org email address or announce@apache will reject it.
+
+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.
== 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`. The dependencies are listed in `solr-ref-guide/README.adoc`.
+
+//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]).
+
+// 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.
=== Publish a New Guide
==== Step 1: Update extpaths.txt in CMS Staging
-. Checkout CMS trunk: `svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source` ('content' is a very generic name. So, we check it out to a self-explanatory name such as 'website-source')
-* If you already have this repo checked out, you can simply do `svn up` to update to the latest revision.
+. 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_Z >> extpaths.txt`
-. Commit changes `svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" 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:
-`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`
+[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