[CONF] Apache Solr Reference Guide > Internal - How To Publish This Documentation

["Hoss Man (Confluence)" <co...@apache.org>]

Space: Apache Solr Reference Guide (https://cwiki.apache.org/confluence/display/solr)
Page: Internal - How To Publish This Documentation (https://cwiki.apache.org/confluence/display/solr/Internal+-+How+To+Publish+This+Documentation)


Edited by Hoss Man:
---------------------------------------------------------------------
{toc}

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|https://www.apache.org/dev/release-signing.html#generate] if you don't have one already.
** Ensure that your key is listed in the [top level KEYS file|https://dist.apache.org/repos/dist/release/lucene/KEYS] as well as the [solr KEYS file|https://dist.apache.org/repos/dist/release/lucene/solr/KEYS]. (Note: this may change pending [LUCENE-5143|https://issues.apache.org/jira/browse/LUCENE-5143].)  If your key is not listed in either file, the following commands can be used to [easily append it|https://www.apache.org/dev/release-signing.html#keys-policy] - modify the URL as needed to update both files...
\\
{noformat}
svn co --non-recursive https://dist.apache.org/repos/dist/release/lucene tmp-release-keys
cd tmp-release-keys
(gpg --list-sigs <your name> && gpg --armor --export <your name>) >> KEYS
svn commit -m "adding my key"
cd ../
rm -rf tmp-release-keys
{noformat}


h1. How To Create a Ref-Guide Release Candidate

* Check out the {{lucene/solr/ref-guide}} directory from the [dist/dev repo|https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/] (or svn update if you already have a checkout) to [host the ref guide RC|https://www.apache.org/dev/release#host-rc]:
\\
{noformat}
svn co https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide solr-ref-guide-rc
# OR
svn update solr-ref-guide-rc
# THEN
cd solr-ref-guide-rc
{noformat}
* Load [The PDF Space Export Page|https://cwiki.apache.org/confluence/spaces/flyingpdf/flyingpdf.action?key=solr] 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 {{[prep-solr-ref-guide-rc.sh|https://svn.apache.org/repos/asf/lucene/dev/trunk/dev-tools/scripts/prep-solr-ref-guide-rc.sh]}} 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..
\\
{noformat}
hossman@frisbee:~/tmp/solr-ref-guide-rc$ ~/lucene-trunk/dev/dev-tools/scripts/prep-solr-ref-guide-rc.sh 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 <yo...@apache.org>"
4096-bit RSA key, ID DEADBEEF, created 1969-07-04
{noformat}
* SVN Add & Commit the new RC sub-directory...
\\
{noformat}
svn add apache-solr-ref-guide-X.Y-RCZ
svn commit -m "X.Y ref guide RCZ"
{noformat}

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: {{https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ}}.
* 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|http://www.apache.org/foundation/voting.html#ReleaseVotes]...

* Run the {{[publish-solr-ref-guide-rc.sh|https://svn.apache.org/repos/asf/lucene/dev/trunk/dev-tools/scripts/publish-solr-ref-guide-rc.sh]}} script using the {{X.Y-RCZ}} version+RC# of the release candidate whose vote succeeded.
* The {{publish-solr-ref-guide-rc.sh}} does not (currently) do any direct publishing, instead it outputs the SVN commands you should run to execute a "remove move" of the RC files into the final {{dist/releases}} directory.  For example...
\\
{noformat}
hossman@frisbee:~/tmp/solr-ref-guide-rc$ ~/lucene-trunk/dev/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
{noformat}
* 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/poll-mirrors.pl}}...
\\
{noformat}
perl dev-tools/scripts/poll-mirrors.pl -details -p lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf
{noformat}

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: {{https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf}}

When linking to "old" versions of the ref guide, always use archive.apache.org. Example: {{https://archive.apache.org/dist/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf}}

h3. Website (lucene.apache.org)

* 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|http://lucene.apache.org/solr/documentation.html] only has a general link to the mirror network for the [ref-guide directory|https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/]
* (!) Special 4.5 release action item:
** Once multiple versions of the ref guide exists, add verbage to the [doc page|http://lucene.apache.org/solr/documentation.html] along the lines of:{noformat}
Archives for all past versions of the Solr Reference Guide are available at
[the Apache archives](http://archive.apache.org/dist/lucene/solr/ref-guide/).
{noformat}


h3. Confluence

* On the [Confluence Theme Configuration Page|https://cwiki.apache.org/confluence/spaces/doctheme/configuretheme.action?key=solr] 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|https://cwiki.apache.org/confluence/spaces/flyingpdf/viewpdflayoutconfig.action?key=solr] 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|https://lucene.apache.org/solr/documentation.html], or be to specific pages of the dynamic wiki site -- but it may be a good idea to skim the [front page|https://wiki.apache.org/solr/] 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 @apache.org 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)

h2. Remove Archived Versions From the Mirrors

Shortly after new releases are first mirrored, they are copied to archive.apache.org. Only the latest point release from each active branch should be kept under the Lucene PMC svnpubsub area {{dist/releases/lucene/}}. Older releases can be safely deleted since these releases are already backed up in the archives. Example...

{noformat}
svn rm -m "remove archived ref guide X.Y" https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf.sha1 https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf.asc
{noformat} 

h2. Remove Residual RC Files / Directories

If there were multiple iterations of release candiates (ie: RC0, RC1, RC2) there will still be left over RC directories in the {{dist/dev}} repo.  These can easily be cleaned up using your existing {{solr-ref-guide-rc}} working directory...

{noformat}
cd solr-ref-guide-rc
svn update
svn rm *
svn commit -m "Clean up residual files from X.Y release candidates"
{noformat}



Stop watching space: https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=solr
Change email notification preferences: https://cwiki.apache.org/confluence/users/editmyemailsettings.action