Author: crossley
Date: Sat Sep 13 02:37:40 2008
New Revision: 694908
URL: http://svn.apache.org/viewvc?rev=694908&view=rev
Log:
Add two new docs:
"How to deploy documentation with the Forrestbot svn workstage" which
explains how the Apache Forrest project manages their project documentation,
"How to deploy documentation with the Forrestbot scp workstage" which
explains how to manage a personal or company website using Secure Shell
SCP to deploy the generated documents.
Added:
forrest/trunk/site-author/content/xdocs/howto-forrestbot-scp.xml (with
props)
forrest/trunk/site-author/content/xdocs/howto-forrestbot-svn.xml
- copied, changed from r694674,
forrest/trunk/site-author/content/xdocs/docs_0_90/howto/howto-forrestbot.xml
Removed:
forrest/trunk/site-author/content/xdocs/docs_0_90/howto/howto-forrestbot.xml
Modified:
forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml
forrest/trunk/site-author/content/xdocs/site.xml
forrest/trunk/site-author/content/xdocs/tools/forrestbot.xml
forrest/trunk/site-author/status.xml
Added: forrest/trunk/site-author/content/xdocs/howto-forrestbot-scp.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/howto-forrestbot-scp.xml?rev=694908&view=auto
==============================================================================
--- forrest/trunk/site-author/content/xdocs/howto-forrestbot-scp.xml (added)
+++ forrest/trunk/site-author/content/xdocs/howto-forrestbot-scp.xml Sat Sep 13
02:37:40 2008
@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
"http://forrest.apache.org/dtd/howto-v20.dtd";>
+<howto>
+ <header>
+ <title>How to deploy documentation with the Forrestbot "scp"
workstage</title>
+ <abstract>
+ This How-To describes the building and deployment of a documentation set
+ with the help of the forrestbot "scp" workstage.
+ </abstract>
+ <last-modified-content-date date="2008-09-12"/>
+ </header>
+ <audience title="Intended Audience">
+ <p>
+ Anyone who generates a static documentation set with Forrest will need
+ to deploy the results, whether that be to a remote server or locally.
+ </p>
+ </audience>
+ <purpose title="Purpose">
+ <p>
+ This howto will explain one method of using the Forrestbot, by way of the
+ worked example for managing a company or private website, and using
"Secure Copy (SCP)" to deploy to a remote webserver. The Forrestbot has a
number of deployment methods. After you understand the principles then you will
be able to apply that to whatever method is relevant.
+ </p>
+ <p>
+ The secondary purpose is to explain to ASF committers how to manage
+ project documentation, e.g. for an "Apache Labs" investigation.
+ </p>
+ <p>
+ This howto also explains the use of the Apache Cocoon "checksums"
facility
+ to only process and deploy the changed files.
+ </p>
+ </purpose>
+ <prerequisites title="Prerequisites">
+ <p>
+ Refer to the <a href="site:forrestbot">Forrestbot</a> documentation.
+ It is not necessary to have thorough knowledge, but a basic understanding
+ will help.
+ </p>
+ <p>
+ An account on a server configured to use SSH access.
+ e.g. <a href="http://apache.org/dev/new-committers-guide.html#ssh";>ASF
Guide for new committers</a>.
+ </p>
+ <p>
+ Review the <a href="site:forrestbot-svn">Forrestbot svn</a> howto
documentation.
+ That explains more generally how to use a Forrestbot.
+ </p>
+ <p>
+ Therefore this "scp" howto can have minimal content.
+ </p>
+ </prerequisites>
+ <steps title="Steps">
+ <section id="introduction">
+ <title>Introduction</title>
+ <p>
+ This Forrestbot uses the "getsrc.local" workstage to retrieve the
sources from the local project workspace filesystem, i.e. from the top-level of
your Forrest project site.
+ </p>
+ <p>
+ This Forrestbot uses the "deploy.scp" workstage to copy the generated
documents
+ to the remote server. They go into a "stage" directory on the web
server
+ which has a .htaccess file to enable selected people to review before
putting into production.
+ </p>
+ </section>
+ <section id="settings">
+ <title>The deploy.scp.settings file</title>
+ <p>
+ Create a file at the top-level of your project site named
+ <code>deploy.scp.settings</code> to provide your ssh credentials.
+ Set its file permissions so that only you can read it.
+ </p>
+ <source><![CDATA[<?xml version="1.0"?>
+<project>
+ <property name="deploy.scp.keyfile" value="/Users/me/.ssh/id_rsa"/>
+ <property name="deploy.scp.passphrase" value="#$!*%#..."/>
+</project>]]></source>
+ </section>
+ <section id="buildfile">
+ <title>The Forrestbot buildfile</title>
+ <p>
+ The Forrestbot buildfile sets some properties and declares the
workstages (i.e. Ant targets) that need to be carried out. Of course this is
fully explained in the <a href="site:forrestbot">Forrestbot</a>
+ documentation.
+ </p>
+ <p>
+ Create a file at the top-level of your project website named, e.g.
+ <code>publish-stage.xml</code>
+ </p>
+ <source><![CDATA[<?xml version="1.0"?>
+<project name="my-lab-docs" default="main">
+ <property name="getsrc.local.root-dir" location="."/>
+ <target name="getsrc" depends="getsrc.clean-workdir, getsrc.local"/>
+ <property name="deploy.scp.dest"
+ value="[EMAIL PROTECTED]:public_html/my-lab/stage"/>
+ <import file="deploy.settings" optional="true"/>
+ <target name="deploy" depends="deploy.scp"/>
+ <property environment="env"/>
+ <import file="${env.FORREST_HOME}/tools/forrestbot/core/forrestbot.xml"/>
+</project>]]></source>
+ <p>
+ So it gets the sources relative to the current directory. Actually
+ it reads the <code>forrest.properties</code> configuration file
+ to find out where other stuff is located.
+ </p>
+ <p>
+ It deploys the generated files directly to the user's "public_html"
webspace
+ into a "stage" sub-directory. Of course this "deploy.scp.dest" location
+ could be a full pathname to an htdocs directory on the remove remote
server.
+ </p>
+ </section>
+ <section id="checksums">
+ <title>The Cocoon "checksums" facility</title>
+ <p>
+ Instruct Forrest's Cocoon to use a "checksums" file to record the
checksum
+ of each document that it has processed. This enables subsequent builds
to
+ only process the documents that have changed. This means that each
file's
+ timestamp will only be touched if it is a changed document, which
enables
+ the Forrestbot deploy.scp workstage to only deploy the changed files.
+ </p>
+ <p>
+ Follow the "<a href="site:faq/checksums">checksums</a>" FAQ.
+ </p>
+ </section>
+ <section id="build">
+ <title>The "build" workstage</title>
+ <p>
+ After doing the usual process to edit source documents, review them
with
+ 'forrest run', and ensure that things are in order with 'forrest
validate'.
+ </p>
+ <p>
+ Now do the build:
+ </p>
+ <source>forrest -f publish-stage.xml build</source>
+ <p>
+ This does the normal site build to generate the complete set of static
documents. Watch for errors.
+ </p>
+ <p>
+ To review, see the built docs in <code>build/my-lab-docs</code>
directory.
+ </p>
+ </section>
+ <section id="deploy">
+ <title>The "deploy" workstage</title>
+ <p>
+ When satisfied, then deploy the built docs:
+ </p>
+ <source>forrest -f publish-satge.xml deploy</source>
+ <p>
+ The files that are being transferred to the remote server will now be
listed.
+ </p>
+ </section>
+ <section id="production">
+ <title>Moving the documents into production</title>
+ <p>
+ The reason for deploying the documents into a "stage" directory was so
that
+ clients or collaborators could review it before going into production.
+ So ask them to review your people.apache.org/my-lab/stage/ site.
+ When satisfied, then:
+ </p>
+ <source>ssh people.apache.org
+cd publish_html/my-lab/stage
+cp -Rf * ..
+</source>
+ <p>
+ That is it.
+ </p>
+ </section>
+ </steps>
+ <extension title="Further Reading">
+ <ul>
+ <li><a href="site:forrestbot-svn">How to deploy documentation with the
Forrestbot "svn" workstage</a></li>
+ <li><a href="site:forrestbot">Forrestbot - automated building and
deploying</a></li>
+ </ul>
+ </extension>
+</howto>
Propchange: forrest/trunk/site-author/content/xdocs/howto-forrestbot-scp.xml
------------------------------------------------------------------------------
svn:eol-style = native
Copied: forrest/trunk/site-author/content/xdocs/howto-forrestbot-svn.xml (from
r694674,
forrest/trunk/site-author/content/xdocs/docs_0_90/howto/howto-forrestbot.xml)
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/howto-forrestbot-svn.xml?p2=forrest/trunk/site-author/content/xdocs/howto-forrestbot-svn.xml&p1=forrest/trunk/site-author/content/xdocs/docs_0_90/howto/howto-forrestbot.xml&r1=694674&r2=694908&rev=694908&view=diff
==============================================================================
---
forrest/trunk/site-author/content/xdocs/docs_0_90/howto/howto-forrestbot.xml
(original)
+++ forrest/trunk/site-author/content/xdocs/howto-forrestbot-svn.xml Sat Sep 13
02:37:40 2008
@@ -15,70 +15,179 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.2//EN"
"http://forrest.apache.org/dtd/howto-v12.dtd";>
+<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
"http://forrest.apache.org/dtd/howto-v20.dtd";>
<howto>
<header>
- <title>How to deploy your site with the forrestbot via a cron job</title>
+ <title>How to deploy documentation with the Forrestbot "svn"
workstage</title>
<abstract>
- This How-To describes the deployment of a forrest documentation with the
- help of the forrestbot. This deployment task will then be automated via a
- cron tab.
+ This How-To describes the building and deployment of a documentation set
+ with the help of the forrestbot "svn" workstage.
</abstract>
- <last-modified-content-date date="2005-07-19"/>
+ <last-modified-content-date date="2008-09-12"/>
</header>
<audience title="Intended Audience">
<p>
- Users who need to deploy a forrest documentation on a regular basis and
- want to automate this task.
+ Anyone who generates a static documentation set with Forrest will need
+ to deploy the results, whether that be to a remote server or locally.
</p>
</audience>
<purpose title="Purpose">
<p>
- If you are administrate a forrest documentation and have to deploy it on
a
- regular basis the process is sometimes quite time consuming. One feature
- of forrest is the forrestbot. This bot can build the documentation and
- later on deploy it to a server of your choice. You will learn how to use
- this forrestbot and how to mae programmed deployments.
+ This howto will explain one method of using the Forrestbot, by way of the
+ worked example for managing the Apache Forrest project website. The
Forrestbot has a number of deployment methods. After you understand the
principles then you will be able to apply that to whatever method is relevant.
+ </p>
+ <p>
+ The secondary purpose is to explain to Forrest committers how to manage
+ our project documentation. Other ASF projects will also find it useful.
</p>
</purpose>
<prerequisites title="Prerequisites">
- <ul>
- <li>Understand how the forrestbot works in following the
- <link href="site:forrestbot">Forrestbot</link> document.</li>
- </ul>
+ <p>
+ Refer to the <a href="site:forrestbot">Forrestbot</a> documentation.
+ It is not necessary to have thorough knowledge, but a basic understanding
+ will help.
+ </p>
</prerequisites>
<steps title="Steps">
- <section id="sitemap">
- <title>Create your project's main sitemap.xmap</title>
+ <section id="introduction">
+ <title>Introduction</title>
+ <p>
+ In this document "we/our" refers to the Apache Forrest project
committers, who
+ manage the documentation. Even though other developers can help to
+ enhance the documentation by way of contributed patches, only the set
of
+ committers can deploy (publish) it.
+ </p>
<p>
- In the <link href="site:forrestbot">Forrestbot</link> document you have
- seen an example of a buildfile for a cvs source. We will now use a
local
- source.
- </p>
- <source>
-<![CDATA[<project name="mysampleproject" default="main" >
- <property name="notify.email.host" value="smtp.myhost.com"/>
- <property name="notify.email.to" value="[EMAIL PROTECTED]"/>
- <property name="notify.administrator" value="Your Name <[EMAIL
PROTECTED]>"/>
- <property name="getsrc.local.root-dir" value="/path/to/project/dir"/>
- <property name="deploy.scp.dest" value="[EMAIL
PROTECTED]:/path/to/project/www-docs"/>
-
- <!-- ant targets -->
- <target name="notify" depends="notify.local, notify.email"/>
- <target name="deploy" depends="deploy.scp"/>
- <target name="getsrc" depends="getsrc.local"/>
-
- <!-- assumes FORREST_HOME has been set as an environment variable -->
- <property environment="env"/>
- <import file="${env.FORREST_HOME}/../forrestbot/core/forrestbot.xml"/>
-</project> ]]>
- </source>
+ Our source documents are managed in the project's Subversion (SVN)
version control system. Each committer has a local SVN working copy on their
office computer. We can prepare source changes and review them with 'forrest
run' and 'forrest validate-xdocs'. When satisfied we 'svn commit' those
changes. Our Forrestbot uses the "getsrc.local" workstage to retrieve the
sources from the local svn checkout.
+ </p>
+ <p>
+ The generated static documents which form the website are also stored
in SVN. So our Forrestbot uses the "deploy.svn" workstage to deploy the
generated documents. To publish the website, a regular cron job on the
apache.org server automatically does 'svn update' in the website's document
space. Elegant.
+ </p>
+ <p>
+ That is what we call a "local forrestbot". Each committer can conduct
+ the workstages on their local computer. This enables a distributed
team to manage the documentation.
+ </p>
+ <p>
+ We have another Forrestbot on our "zone"
+ <a href="http://forrest.zones.apache.org/";>demonstration server</a>.
+ It runs automatically via cron each hour. Its workstages are not
described in this howto, but essentially it gets the sources using the
"getsrc.svn" workstage and it deploys the results to the local webserver htdocs
directory on that machine using the "deploy.local" workstage. See that <a
href="http://svn.apache.org/repos/asf/forrest/zone/htdocs/ft/forrest-docs.xml";>buildfile</a>.
+ </p>
+ </section>
+ <section id="follow">
+ <title>Follow along on your local system</title>
+ <p>
+ You have all the sources for the Forrest project in your Forrest
distribution in the "$FORREST_HOME/site-author" directory. If you are using the
release then you have a snapshot of the documentation. Of course if you have
SVN trunk then you are up-to-date.
+ </p>
+ <p>
+ The Forrestbot build files for our site are also available. This means
that you can run the "build" workstage. However you will not be able to do the
"deploy" worskstage unless you are a Forrest committer.
+ </p>
+ <p>
+ There is a brief explanation of how to publish our site in the document
+ <a
href="http://svn.apache.org/repos/asf/forrest/trunk/etc/publishing_our_site.txt";>$FORREST_HOME/etc/publishing_our_site.txt</a>
+ </p>
+ </section>
+ <section id="settings">
+ <title>The deploy.svn.settings file</title>
+ <p>
+ As explained in the above document, each committer needs a
+ <code>deploy.svn.settings</code> file to provide their credentials.
+ </p>
+ <source><![CDATA[<?xml version="1.0"?>
+<project>
+ <property name="deploy.svn.user" value="myApacheUsername"/>
+ <property name="deploy.svn.password" value="mySvnPassword"/>
+</project>]]></source>
+ </section>
+ <section id="buildfile">
+ <title>The Forrestbot buildfile</title>
+ <p>
+ The Forrestbot buildfile sets some properties and declares the
workstages (i.e. Ant targets) that need to be carried out. Of course this is
fully explained in the <a href="site:forrestbot">Forrestbot</a>
+ documentation.
+ </p>
+ <p>
+ Our buildfile is at
+ <a
href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/publish.xml";>$FORREST_HOME/site-author/publish.xml</a>
+ ...
+ </p>
+ <source><![CDATA[<?xml version="1.0"?>
+<project name="forrest-docs" default="main">
+ <property name="getsrc.local.root-dir" location="."/>
+ <target name="getsrc" depends="getsrc.clean-workdir, getsrc.local"/>
+ <import file="../deploy.svn.settings" optional="true"/>
+ <property name="deploy.svn.url"
+ value="https://svn.apache.org/repos/asf/forrest/site"/>
+ <target name="deploy" depends="deploy.svn"/>
+ <property environment="env"/>
+ <import file="${env.FORREST_HOME}/tools/forrestbot/core/forrestbot.xml"/>
+</project>]]></source>
+ <p>
+ So it gets the sources relative to the current directory. Actually
+ it reads the <code>forrest.properties</code> configuration file
+ to find out where other stuff is located.
+ </p>
+ <p>
+ It deploys the generated files directly to the forrest/site SVN
repository.
+ </p>
+ </section>
+ <section id="build">
+ <title>The "build" workstage</title>
+ <p>
+ After doing the usual process to edit source documents, review them
with
+ 'forrest run', and ensure that things are in order with 'forrest
validate'.
+ </p>
+ <p>
+ Now do the build:
+ </p>
+ <source>cd $FORREST_HOME/site-author
+forrest -f publish.xml build</source>
+ <p>
+ This does the normal site build to generate the complete set of static
documents. Watch for errors.
+ </p>
+ <p>
+ To review, see the built docs in <code>build/forrest-docs</code>
directory.
+ </p>
+ </section>
+ <section id="deploy">
+ <title>The "deploy" workstage</title>
+ <p>
+ When satisfied, then deploy the built docs:
+ </p>
+ <source>forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my
commit message"</source>
+ <p>
+ If no commit message is supplied, then forrestbot will use a default.
+ </p>
+ <p>
+ Now don't get frightened. It might seem like nothing is happening.
+ The first time that the "deploy" worskstage is used it will need to
+ do an 'svn checkout' of the site repository. This will take some time.
+ On subsequent deploys, it will need to do an 'svn update'. So be
patient.
+ </p>
+ <p>
+ The files that are being committed will now be listed. That is it.
+ They are now in the "<a
href="http://svn.apache.org/repos/asf/forrest/site";>forrest/site</a>" SVN
repository.
+ </p>
+ </section>
+ <section id="production">
+ <title>Moving the documents into production</title>
+ <p>
+ Next a cron job on the server will automatically publish it.
+ However, if quicker turnaround is required, then do this:
+ </p>
+ <source>ssh people.apache.org
+cd /www/forrest.apache.org
+umask 002
+svn update</source>
+ <p>
+ Next an rsync cronjob will publish it to the production webserver.
+ See other <a href="http://apache.org/dev/project-site.html";>notes</a>
+ about how the ASF project websites are managed.
+ </p>
</section>
</steps>
- <feedback title="Feedback and further development of this How-To">
- <p>
- Please provide feedback about this document via the
- <link href="site:mail-lists">mailing lists</link>.
- </p>
- </feedback>
+ <extension title="Further Reading">
+ <ul>
+ <li><a href="site:forrestbot-scp">How to deploy documentation with the
Forrestbot "scp" workstage</a></li>
+ <li><a href="site:forrestbot">Forrestbot - automated building and
deploying</a></li>
+ </ul>
+ </extension>
</howto>
Modified:
forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml?rev=694908&r1=694907&r2=694908&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml
(original)
+++ forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml
Sat Sep 13 02:37:40 2008
@@ -69,14 +69,18 @@
<p>
This builds the documentation locally then deploys it by committing it
to the
- <a href="https://svn.apache.org/repos/asf/forrest/site";>forrest/site
+ <a href="http://svn.apache.org/repos/asf/forrest/site";>forrest/site
SVN</a>. Then a cronjob on the server will automatically publish it.
- However, if instant turnaround is required, then do this:
+ However, if quicker turnaround is required, then do this:
</p>
<source>ssh people.apache.org
cd /www/forrest.apache.org
svn update</source>
<p>
+ See more detailed <a href="site:forrestbot-svn">explanation</a> of this
+ procedure.
+ </p>
+ <p>
Publishing documentation for a particular plugin is done by:
</p>
<source>cd plugins/myPluginName
Modified: forrest/trunk/site-author/content/xdocs/site.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/site.xml?rev=694908&r1=694907&r2=694908&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/site.xml (original)
+++ forrest/trunk/site-author/content/xdocs/site.xml Sat Sep 13 02:37:40 2008
@@ -99,6 +99,10 @@
<debug-sitemap-exec href="#debug-sitemap-exec"/>
<debug-validation href="#debug-validation"/>
</forrest-dev>
+ <forrestbot-svn label="Forrestbot svn" href="howto-forrestbot-svn.html"
+ description="Publish documentation with Forrestbot svn workstage"/>
+ <forrestbot-scp label="Forrestbot scp" href="howto-forrestbot-scp.html"
+ description="Publish documentation with Forrestbot scp workstage"/>
<svnBP label="Subversion" href="subversion_bestpractices.html"
description="Best practice notes for Subversion"/>
<docsBP label="Documentation" href="documentation_bestpractices.html"
Modified: forrest/trunk/site-author/content/xdocs/tools/forrestbot.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/tools/forrestbot.xml?rev=694908&r1=694907&r2=694908&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/tools/forrestbot.xml (original)
+++ forrest/trunk/site-author/content/xdocs/tools/forrestbot.xml Sat Sep 13
02:37:40 2008
@@ -696,5 +696,12 @@
<code><import></code> task (see the example above).
</p>
</section>
+ <section id="refs">
+ <title>Further Reading</title>
+ <ul>
+ <li><link href="site:forrestbot-svn">How to deploy documentation with
the Forrestbot "svn" workstage</link></li>
+ <li><link href="site:forrestbot-scp">How to deploy documentation with
the Forrestbot "scp" workstage</link></li>
+ </ul>
+ </section>
</body>
</document>
Modified: forrest/trunk/site-author/status.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/status.xml?rev=694908&r1=694907&r2=694908&view=diff
==============================================================================
--- forrest/trunk/site-author/status.xml (original)
+++ forrest/trunk/site-author/status.xml Sat Sep 13 02:37:40 2008
@@ -152,6 +152,15 @@
<link href="site:upgrading_09">upgrading to v0.9</link>
</action>
<!-- 2008-09 -->
+ <action context="docs" type="add" dev="DC">
+ Added new documents: <link href="site:forrestbot-svn">How to deploy
+ documentation with the Forrestbot "svn" workstage</link> which
+ explains how the Apache Forrest project manages their project
documentation,
+ and <link href="site:forrestbot-scp">How to deploy
+ documentation with the Forrestbot "scp" workstage</link> which
+ explains how to manage a personal or company website using Secure Shell
+ SCP to deploy the generated documents.
+ </action>
<action context="code" type="update" dev="TS, DC"
fixes-bug="FOR-955,FOR-1017" importance="high">
Our packaged version of Apache Cocoon has been upgraded to use the
latest version of their stable 2.1 branch. This is a major step forward
