lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hoss Man (Confluence)" <>
Subject [CONF] Apache Solr Reference Guide > Internal - How To Publish This Documentation
Date Thu, 10 Oct 2013 00:31:00 GMT
Space: Apache Solr Reference Guide (
Page: Internal - How To Publish This Documentation (

Change Comment:

Edited by Hoss Man:

h1. Pre-publication Actions

* Make sure that the [Upgrading Solr] page is up to date for the current version.
* Sanity check that none of the [post-publishing version number updating steps|#Update Links
& Version Numbers] from the last version published were skipped.
* If you have never done a Ref-Guide release before...
** Create a [GPG key to sign the relase|]
if you don't have one already.
** Ensure that your key is listed in the [top level KEYS file|]
as well as the [solr KEYS file|].
(Note: this may change pending [LUCENE-5143|].)
 If your key is not listed in either file, the following commands can be used to [easily append
it|] - modify the URL as needed
to update both files...
svn co --non-recursive tmp-release-keys
cd tmp-release-keys
(gpg --list-sigs <your name> && gpg --armor --export <your name>) >>
svn commit -m "adding my key"
cd ../
rm -rf tmp-release-keys

h1. How To Create a Ref-Guide Release Candidate

* Check out the {{lucene/solr/ref-guide}} directory from the [dist/dev repo|]
(or svn update if you already have a checkout) to [host the ref guide RC|]:
svn co solr-ref-guide-rc
# OR
svn update solr-ref-guide-rc
cd solr-ref-guide-rc
* Load [The PDF Space Export Page|]
in your browser
* Uncheck the box next to [** Internal MetaDocs] to suppress it and its children from being
included in the PDF
* Click the "Export" button
* On the subsequent page, wait for a "Download here" link to dynamically appear.
* Click "Download here" and save the PDF into your {{solr-ref-guide-rc}} directory.
* Using {{solr-ref-guide-rc}} as your working directory, run the {{[|]}}
script to prepare the release candidate, specifying the name of the local PDF file you just
exported, and the version+RC# to use (starting with "RC0").  This will create a new subdirectory
containing the properly named RC artifacts, including the .sha1 and .asc files (you will be
prompted for your GPG passphrase, and may optionally specify a GPG public key ID as well if
you don't want to use your default key).  For example..
hossman@frisbee:~/tmp/solr-ref-guide-rc$ ~/lucene-trunk/dev/dev-tools/scripts/
solr-123456-7890-6543.pdf X.Y-RCZ DEADBEEF
+ mkdir apache-solr-ref-guide-X.Y-RCZ
+ mv solr-123456-7890-6543.pdf apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf
+ cd apache-solr-ref-guide-X.Y-RCZ
+ sha1sum apache-solr-ref-guide-X.Y.pdf
+ gpg -u DEADBEEF --armor --output apache-solr-ref-guide-X.Y.pdf.asc --detach-sig apache-solr-ref-guide-X.Y.pdf

You need a passphrase to unlock the secret key for
user: "Your Name <>"
4096-bit RSA key, ID DEADBEEF, created 1969-07-04
* SVN Add & Commit the new RC sub-directory...
svn add apache-solr-ref-guide-X.Y-RCZ
svn commit -m "X.Y ref guide RCZ"

h1. Hold a VOTE

* Send an email to dev@lucene (CC general@lucene) with a Subject "VOTE: RC0 Release apache-solr-ref-guide-X.Y.pdf"
and include the full URL from of the RC directory in the {{dist/dev}} repo.  Example: {{}}.
* Don't forget to send an email with your own +1 VOTE
* If there are problems with the RC that are fixed in Confluence, export & prepare a new
RC (using the instructions above) with a new name (RC1, RC2, etc...) and send out another
VOTE thread.

h1. Publish to SvnSubPub & Mirrors

Once [three PMC members have voted for a release, it may be published|]...

* Run the {{[|]}}
script using the {{X.Y-RCZ}} version+RC# of the release candidate whose vote succeeded.
* The {{}} does not (currently) do any direct publishing, instead
it outputs the SVN commands you should run to execute a "remote move" of the RC files into
the final {{dist/releases}} directory.  For example...
hossman@frisbee:~/tmp/solr-ref-guide-rc$ ~/lucene-trunk/dev/dev-tools/scripts/
## Run the following commands when ready...
svn move -m 'publishing apache-solr-ref-guide-X.Y-RCZ'
svn rm -m 'cleaning up apache-solr-ref-guide-X.Y-RCZ'
* Wait 24 hours to give the mirrors a chance to get the new release. The status of the mirrors
can be monitored using {{dev-tools/scripts/}}...
perl dev-tools/scripts/ -details -p lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf
* If the Ref Guide is being released at nearly the same time as the code, the new guide should
be mentioned in the code release announcement.  Now is the time to start coordinating that,
by editing the announcement draft on the MoinMoin wiki, e.g. for the 4.5 release: [].

h1. Post Publish Actions

Once most mirrors have been updated, we can link to (and announce) the new guide.

h2. Update Links & Version Numbers

When linking to the "current" version of the ref guide, always use the download redirector.
Example: {{}}

When linking to "old" versions of the ref guide, always use Example: {{}}

h3. Website (

* Check if any links on the website need updated
** For now (as of July 28, 2013) there is no direct link to any specific version(s) of the
ref guide from the website -- for simplicity the [doc page|]
only has a general link to the mirror network for the [ref-guide directory|]
* (!) Special 4.5 release action item:
** Once multiple versions of the ref guide exists, add verbage to the [doc page|]
along the lines of:{noformat}
Archives for all past versions of the Solr Reference Guide are available at
[the Apache archives](

h3. Confluence

* On the [Confluence Theme Configuration Page|]
for the Solr Ref Guide...
** Update the Left Nav to add a link to the current version of the ref guide.
** Update the Left Nav to change the link for the previous version(s) of the ref guide so
that they use the archive URL.
** Update the Left Nav and Header "Message" to refer to the "next" version that the live copy
of the documentation will refer to (ie: if the 4.4 ref guide has just been published, change
"_*4.4* Draft Ref Guide Topics_" to "_*4.5* Draft Ref Guide Topics_" and "_This Unreleased
Guide Will Cover Apache Solr *4.4*_" to "_This Unreleased Guide Will Cover Apache Solr *4.5*_")
* On the [Confluence PDF Layout Page|]
for the Solr Ref Guide...
** Update the "Title Page" to refer to the "next" version (ie: 4.4 \-> 4.5)
** Update the "Footer" to refer to the "next" version (ie: 4.4 \-> 4.5)
* On the [Upgrading Solr] page:
** Rename the the first "Upgrading from 4.Y.x" section to mach the version just pulished (ie:
if 4.4 was just published name it "Upgrading from 4.4.x")
** Summarize any extremely important items and move them down to the "Upgrading from Older
Versions of Solr" section.
** Empty out the "Upgrading from 4.Y.x" in preparation for new information to be added

h3. Community Wiki

The MoinMoin wiki should not have any major links to specific released version of the ref
guide -- any links should either be funnelled through [the main doc page|],
or be to specific pages of the dynamic wiki site -- but it may be a good idea to skim the
[front page|] to sanity check that this is still true.

h2. Announce

Announce the new Guide on solr-user@lucene, CCing general@lucene and announce@apache.

{note}You must send the announcement email from your address or announce@apache
will automatically reject it{note}

If the Ref Guide is being released at nearly the same time as the code, it may make sense
to just mention the new guide in the main release announcement, which is usually authored
on the MoinMoin wiki, e.g. [].

If the Ref Guide release is announced separately from the code release, the Solr News page
should be updated to include the Ref Guide release announcement: [],
using e.g. the [ASF CMS bookmarklet|] to edit the page.

h2. Remove Archived Releases and Residual RCs From the 'dist' Repository

Shortly after new releases are first mirrored, they are copied to  Only
the latest point release from each active branch (in the case of the ref guide, we only do
point releases from the stable branch) should be kept in the {{dist/releases/lucene}} repo
directory. Older releases can be safely deleted since they have already backed up in the archives.

In addition, if there were multiple iterations of release candidates (ie: RC0, RC1, RC2) there
will still be left over RC directories in the {{dist/dev/lucene}} repo directory.  These should
also be removed.

* Run the {{[|]}}
script using the {{X.Y}} version# of the ref guide that has just been published.
* The {{}} does not (currently) do any direct removal of files
from the repo, instead it outputs the SVN commands you should run to execute a "remote delete"
of the appropriate files.  For example...
$ ~/lucene-trunk/dev-tools/scripts/ X.Y
## Run the following commands when ready...
# Delete old releases
svn rm -m 'removing archived ref guide files prior to X.Y'
# Delete old RC files
svn rm -m 'cleaning up old RCs now that X.Y has been released'

Stop watching space:
Change email notification preferences:


View raw message