[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 "remote 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}
* 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: [https://wiki.apache.org/solr/ReleaseNote45].

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 December 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/]

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 replace the link to the current version of the ref guide.
*** Link Text: _*4.6* Ref Guide (PDF Download)_ -> _*4.7* Ref Guide (PDF Download)_
*** Link URL: _apache\-solr\-ref\-guide\-*4.6*.pdf_ \-> _apache\-solr\-ref\-guide-*4.7*.pdf_
** 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, which is usually authored on the MoinMoin wiki, e.g. [https://wiki.apache.org/solr/ReleaseNote45].

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: [http://lucene.apache.org/solr/solrnews.html], using e.g. the [ASF CMS bookmarklet|https://cms.apache.org/#bookmark] 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 archive.apache.org.  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 {{[archive-solr-ref-guide-rc.sh|https://svn.apache.org/repos/asf/lucene/dev/trunk/dev-tools/scripts/archive-solr-ref-guide-rc.sh]}} script using the {{X.Y}} version# of the ref guide that has just been published.
* The {{archive-solr-ref-guide-rc.sh}} 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...
\\
{noformat}
$ ~/lucene-trunk/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/
{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