howto-forrestbot-svn.html - forrest - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <meta content="Apache Forrest" name="Generator">
 <meta name="Forrest-version" content="0.9-dev">
 <meta name="Forrest-skin-name" content="pelt">
 <title>How to deploy documentation with the Forrestbot "svn" workstage</title>
 <link type="text/css" href="skin/basic.css" rel="stylesheet">
 <link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
 <link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
 <link type="text/css" href="skin/profile.css" rel="stylesheet">
 <script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
 <link rel="shortcut icon" href="favicon.ico">
 </head>
 <body onload="init()">
 <script type="text/javascript">ndeSetTextSize();</script>
 <div id="top">
 <!--+
     |breadtrail
     +-->
 <div class="breadtrail">
 <a href="http://www.apache.org/">Apache Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache Forrest</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
 </div>
 <!--+
     |header
     +-->
 <div class="header">
 <!--+
     |start group logo
     +-->
 <div class="grouplogo">
 <a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="images/apache-forrest.png" title="The Apache Software Foundation"></a>
 </div>
 <!--+
     |end group logo
     +-->
 <!--+
     |start Project Logo
     +-->
 <div class="projectlogo">
 <a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="images/project-logo.gif" title="Apache Forrest"></a>
 </div>
 <!--+
     |end Project Logo
     +-->
 <!--+
     |start Search
     +-->
 <div class="searchbox">
 <form action="http://www.google.com/search" method="get" class="roundtopsmall">
 <input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
                     <input name="Search" value="Search" type="submit">
 </form>
 </div>
 <!--+
     |end search
     +-->
 <!--+
     |start Tabs
     +-->
 <ul id="tabs">
 <li>
 <a class="unselected" href="index.html">Welcome</a>
 </li>
 <li class="current">
 <a class="selected" href="contrib.html">Developers</a>
 </li>
 <li>
 <a class="unselected" href="versions/index.html">Versioned Docs</a>
 </li>
 <li>
 <a class="unselected" href="pluginDocs/index.html">Plugins</a>
 </li>
 <li>
 <a class="unselected" href="tools/index.html">Tools</a>
 </li>
 </ul>
 <!--+
     |end Tabs
     +-->
 </div>
 </div>
 <div id="main">
 <div id="publishedStrip">
 <!--+
     |start Subtabs
     +-->
 <div id="level2tabs"></div>
 <!--+
     |end Endtabs
     +-->
 <script type="text/javascript"><!--
 document.write("Last Published: " + document.lastModified);
 //  --></script>
 </div>
 <!--+
     |breadtrail
     +-->
 <div class="breadtrail">

              &nbsp;
            </div>
 <!--+
     |start Menu, mainarea
     +-->
 <!--+
     |start Menu
     +-->
 <div id="menu">
 <div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
 <div id="menu_1.1" class="menuitemgroup">
 <div class="menuitem">
 <a href="contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
 </div>
 <div class="menuitem">
 <a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
 </div>
 <div class="menuitem">
 <a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
 </div>
 <div class="menuitem">
 <a href="forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
 </div>
 <div class="menuitem">
 <a href="events.html" title="List of upcoming related conferences and meetings">Events</a>
 </div>
 <div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
 <div id="menu_1.1.6" class="menuitemgroup">
 <div class="menuitem">
 <a href="guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
 </div>
 <div class="menuitem">
 <a href="committed.html" title="Notes about contribution">Being committed</a>
 </div>
 <div class="menuitem">
 <a href="tasks.html" title="Tasks to keep the project flowing">Project tasks</a>
 </div>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
 <div id="menu_1.2" class="menuitemgroup">
 <div class="menuitem">
 <a href="asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
 </div>
 <div class="menuitem">
 <a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
 </div>
 <div class="menuitem">
 <a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
 </div>
 <div class="menuitem">
 <a href="svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
 </div>
 <div class="menuitem">
 <a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
 </div>
 <div class="menuitem">
 <a href="gump.html">Gump integration</a>
 </div>
 <div onclick="SwitchMenu('menu_1.2.7', 'skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
 <div id="menu_1.2.7" class="menuitemgroup">
 <div class="menuitem">
 <a href="plan/index.html">Overview</a>
 </div>
 <div class="menuitem">
 <a href="plan/internal-xhtml.html">Internal XHTML</a>
 </div>
 </div>
 <div class="menuitem">
 <a href="todo.html">Todo</a>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Best Practices and Procedures</div>
 <div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
 <div class="menuitem">
 <a href="howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
 </div>
 <div class="menupage">
 <div class="menupagetitle">Forrestbot svn</div>
 </div>
 <div class="menuitem">
 <a href="howto-forrestbot-scp.html" title="Publish documentation with Forrestbot scp workstage">Forrestbot scp</a>
 </div>
 <div class="menuitem">
 <a href="subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
 </div>
 <div class="menuitem">
 <a href="documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
 </div>
 <div class="menuitem">
 <a href="howto-howto.html" title="Instructions for writing             a new howto-document">Write a How-to</a>
 </div>
 <div onclick="SwitchMenu('menu_1.3.7', 'skin/')" id="menu_1.3.7Title" class="menutitle">Committer notes</div>
 <div id="menu_1.3.7" class="menuitemgroup">
 <div class="menuitem">
 <a href="zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
 </div>
 <div class="menuitem">
 <a href="procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
 </div>
 <div class="menuitem">
 <a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest             Website">Publishing Forrest documentation</a>
 </div>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
 <div id="menu_1.4" class="menuitemgroup">
 <div class="menuitem">
 <a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
 </div>
 </div>
 <div id="credit"></div>
 <div id="roundbottom">
 <img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
 <!--+
   |alternative credits
   +-->
 <div id="credit2">
 <a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
 </div>
 </div>
 <!--+
     |end Menu
     +-->
 <!--+
     |start content
     +-->
 <div id="content">
 <div class="trail">Font size:
 	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
 	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
 	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
 </div>
 <h1>How to deploy documentation with the Forrestbot "svn" workstage</h1>
 <div id="front-matter">
 <div class="abstract">
       This How-To describes the building and deployment of a documentation set
       with the help of the forrestbot "svn" workstage.
     </div>
 <div id="minitoc-area">
 <ul class="minitoc">
 <li>
 <a href="#Intended-Audience">Intended Audience</a>
 </li>
 <li>
 <a href="#Purpose">Purpose</a>
 </li>
 <li>
 <a href="#Prerequisites">Prerequisites</a>
 </li>
 <li>
 <a href="#Steps">Steps</a>
 <ul class="minitoc">
 <li>
 <a href="#introduction">Introduction</a>
 </li>
 <li>
 <a href="#follow">Follow along on your local system</a>
 </li>
 <li>
 <a href="#settings">The deploy.svn.settings file</a>
 </li>
 <li>
 <a href="#buildfile">The Forrestbot buildfile</a>
 </li>
 <li>
 <a href="#build">The "build" workstage</a>
 </li>
 <li>
 <a href="#deploy">The "deploy" workstage</a>
 </li>
 <li>
 <a href="#production">Moving the documents into production</a>
 </li>
 </ul>
 </li>
 <li>
 <a href="#faqs">Frequently Asked Questions</a>
 <ul class="minitoc">
 <li>
 <a href="#faq-general">1 General issues</a>
 <ul class="minitoc">
 <li>
 <a href="#1.1+Why+all+the+svn+warnings+about+%22is+already+under+version+control%22">1.1 Why all the svn warnings about "is already under version control"</a>
 </li>
 <li>
 <a href="#1.2+Why+are+there+SVN+diffs+for+some+documents%2C+even+though+they+have+not+changed%3F">1.2 Why are there SVN diffs for some documents, even though they have not changed?</a>
 </li>
 <li>
 <a href="#1.3+Why+is+every+PDF+document+being+deployed%2C+even+though+they+have+not+changed.">1.3 Why is every PDF document being deployed, even though they have not changed.</a>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 <li>
 <a href="#Further-Reading">Further Reading</a>
 </li>
 </ul>
 </div>
 </div>
 <a name="Intended-Audience"></a>
 <h2 class="underlined_10">Intended Audience</h2>
 <div class="section">
 <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>
 </div>
 <a name="Purpose"></a>
 <h2 class="underlined_10">Purpose</h2>
 <div class="section">
 <p>
       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>
 </div>
 <a name="Prerequisites"></a>
 <h2 class="underlined_10">Prerequisites</h2>
 <div class="section">
 <p>
       Refer to the <a href="tools/forrestbot.html">Forrestbot</a> documentation.
       It is not necessary to have thorough knowledge, but a basic understanding
       will help.
     </p>
 </div>
 <a name="Steps"></a>
 <h2 class="underlined_10">Steps</h2>
 <div class="section">
 <a name="introduction"></a>
 <h3 class="underlined_5">Introduction</h3>
 <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>
         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>
 <a name="follow"></a>
 <h3 class="underlined_5">Follow along on your local system</h3>
 <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>
 <a name="settings"></a>
 <h3 class="underlined_5">The deploy.svn.settings file</h3>
 <p>
         As explained in the above document,
         if your "svn username" is different from your local system username
         create <span class="codefrag">$FORREST_HOME/deploy.svn.settings</span> file like:
       </p>
 <pre class="code">&lt;?xml version="1.0"?&gt;
 &lt;project&gt;
   &lt;property name="deploy.svn.user" value="myApacheUsername"/&gt;
 &lt;/project&gt;</pre>
 <a name="buildfile"></a>
 <h3 class="underlined_5">The Forrestbot buildfile</h3>
 <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="tools/forrestbot.html">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>
 <pre class="code">&lt;?xml version="1.0"?&gt;
 &lt;project name="forrest-docs" default="main"&gt;
   &lt;property name="getsrc.local.root-dir" location="."/&gt;
   &lt;target name="getsrc" depends="getsrc.clean-workdir, getsrc.local"/&gt;
   &lt;import file="../deploy.svn.settings" optional="true"/&gt;
   &lt;property name="deploy.svn.url"
     value="https://svn.apache.org/repos/asf/forrest/site"/&gt;
   &lt;target name="deploy" depends="deploy.svn"/&gt;
   &lt;property environment="env"/&gt;
   &lt;import file="${env.FORREST_HOME}/tools/forrestbot/core/forrestbot.xml"/&gt;
 &lt;/project&gt;</pre>
 <p>
         So it gets the sources relative to the current directory. Actually
         it reads the <span class="codefrag">forrest.properties</span> 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>
 <a name="build"></a>
 <h3 class="underlined_5">The "build" workstage</h3>
 <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>
 <pre class="code">cd $FORREST_HOME/site-author
 forrest -f publish.xml build</pre>
 <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 <span class="codefrag">build/forrest-docs</span> directory.
       </p>
 <a name="deploy"></a>
 <h3 class="underlined_5">The "deploy" workstage</h3>
 <p>
         When satisfied, then deploy the built docs:
       </p>
 <pre class="code">forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"</pre>
 <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>
 <a name="production"></a>
 <h3 class="underlined_5">Moving the documents into production</h3>
 <p>
         Next a cron job on the server will automatically publish it.
         However, if quicker turnaround is required, then do this:
       </p>
 <pre class="code">ssh people.apache.org
 cd /www/forrest.apache.org
 umask 002
 svn update</pre>
 <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>
 </div>
 <a name="faqs"></a>
 <h2 class="underlined_10">Frequently Asked Questions</h2>
 <div class="section">
 <a name="faq-general"></a>
 <h3 class="underlined_5">1 General issues</h3>
 <a name="1.1+Why+all+the+svn+warnings+about+%22is+already+under+version+control%22"></a>
 <h4>1.1 Why all the svn warnings about "is already under version control"</h4>
 <p>
             The deploy workstage does 'svn add' for all the generated documents
             that are new - in these cases the normal "A" messages will be issued.
             However it just blindly adds all documents that are either new or
             changed. So the warning messages are issued for the existing, updated
             documents.
           </p>
 <a name="1.2+Why+are+there+SVN+diffs+for+some+documents%2C+even+though+they+have+not+changed%3F"></a>
 <h4>1.2 Why are there SVN diffs for some documents, even though they have not changed?</h4>
 <p>
             These un-necessary differences happen because the comitter who did 'svn add' for those files
             did not have their Subversion client configured properly for the "svn:eol-style" setting.
             See some <a href="tasks.html#subversion-monitoring">notes</a>
             about rectifying this issue.
           </p>
 <a name="1.3+Why+is+every+PDF+document+being+deployed%2C+even+though+they+have+not+changed."></a>
 <h4>1.3 Why is every PDF document being deployed, even though they have not changed.</h4>
 <p>
             The PDF plugins FOP library is automatically adding a datestamp to
             every generated document. We need to find a solution.
             See <a href="https://issues.apache.org/jira/browse/FOR-1077">FOR-1077</a>
             and the <a href="docs_0_90/upgrading_09.html">Upgrading 09</a> document.
           </p>
 </div>
 <a name="Further-Reading"></a>
 <h2 class="underlined_10">Further Reading</h2>
 <div class="section">
 <ul>

 <li>
 <a href="howto-forrestbot-scp.html">How to deploy documentation with the Forrestbot "scp" workstage</a>
 </li>

 <li>
 <a href="tools/forrestbot.html">Forrestbot - automated building and deploying</a>
 </li>

 </ul>
 </div>
 </div>
 <!--+
     |end content
     +-->
 <div class="clearboth">&nbsp;</div>
 </div>
 <div id="footer">
 <!--+
     |start bottomstrip
     +-->
 <div class="lastmodified">
 <script type="text/javascript"><!--
 document.write("Last Published: " + document.lastModified);
 //  --></script>
 </div>
 <div class="copyright">
         Copyright &copy;
          2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
 <br>
     Apache, Apache Forrest, the Apache feather logo, and the Apache Forrest
     logos are trademarks of The Apache Software Foundation.
   </div>
 <!--+
     |end bottomstrip
     +-->
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<meta content="Apache Forrest" name="Generator">
	<meta name="Forrest-version" content="0.9-dev">
	<meta name="Forrest-skin-name" content="pelt">
	<title>How to deploy documentation with the Forrestbot "svn" workstage</title>
	<link type="text/css" href="skin/basic.css" rel="stylesheet">
	<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
	<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
	<link type="text/css" href="skin/profile.css" rel="stylesheet">
	<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
	<link rel="shortcut icon" href="favicon.ico">
	</head>
	<body onload="init()">
	<script type="text/javascript">ndeSetTextSize();</script>
	<div id="top">
	<!--+
	\|breadtrail
	+-->
	<div class="breadtrail">
	<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
	</div>
	<!--+
	\|header
	+-->
	<div class="header">
	<!--+
	\|start group logo
	+-->
	<div class="grouplogo">
	<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="images/apache-forrest.png" title="The Apache Software Foundation"></a>
	</div>
	<!--+
	\|end group logo
	+-->
	<!--+
	\|start Project Logo
	+-->
	<div class="projectlogo">
	<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="images/project-logo.gif" title="Apache Forrest"></a>
	</div>
	<!--+
	\|end Project Logo
	+-->
	<!--+
	\|start Search
	+-->
	<div class="searchbox">
	<form action="http://www.google.com/search" method="get" class="roundtopsmall">
	<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
	<input name="Search" value="Search" type="submit">
	</form>
	</div>
	<!--+
	\|end search
	+-->
	<!--+
	\|start Tabs
	+-->
	<ul id="tabs">
	<li>
	<a class="unselected" href="index.html">Welcome</a>
	</li>
	<li class="current">
	<a class="selected" href="contrib.html">Developers</a>
	</li>
	<li>
	<a class="unselected" href="versions/index.html">Versioned Docs</a>
	</li>
	<li>
	<a class="unselected" href="pluginDocs/index.html">Plugins</a>
	</li>
	<li>
	<a class="unselected" href="tools/index.html">Tools</a>
	</li>
	</ul>
	<!--+
	\|end Tabs
	+-->
	</div>
	</div>
	<div id="main">
	<div id="publishedStrip">
	<!--+
	\|start Subtabs
	+-->
	<div id="level2tabs"></div>
	<!--+
	\|end Endtabs
	+-->
	<script type="text/javascript"><!--
	document.write("Last Published: " + document.lastModified);
	// --></script>
	</div>
	<!--+
	\|breadtrail
	+-->
	<div class="breadtrail">


	</div>
	<!--+
	\|start Menu, mainarea
	+-->
	<!--+
	\|start Menu
	+-->
	<div id="menu">
	<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
	<div id="menu_1.1" class="menuitemgroup">
	<div class="menuitem">
	<a href="contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
	</div>
	<div class="menuitem">
	<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
	</div>
	<div class="menuitem">
	<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
	</div>
	<div class="menuitem">
	<a href="forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
	</div>
	<div class="menuitem">
	<a href="events.html" title="List of upcoming related conferences and meetings">Events</a>
	</div>
	<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
	<div id="menu_1.1.6" class="menuitemgroup">
	<div class="menuitem">
	<a href="guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
	</div>
	<div class="menuitem">
	<a href="committed.html" title="Notes about contribution">Being committed</a>
	</div>
	<div class="menuitem">
	<a href="tasks.html" title="Tasks to keep the project flowing">Project tasks</a>
	</div>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
	<div id="menu_1.2" class="menuitemgroup">
	<div class="menuitem">
	<a href="asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
	</div>
	<div class="menuitem">
	<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
	</div>
	<div class="menuitem">
	<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
	</div>
	<div class="menuitem">
	<a href="svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
	</div>
	<div class="menuitem">
	<a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
	</div>
	<div class="menuitem">
	<a href="gump.html">Gump integration</a>
	</div>
	<div onclick="SwitchMenu('menu_1.2.7', 'skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
	<div id="menu_1.2.7" class="menuitemgroup">
	<div class="menuitem">
	<a href="plan/index.html">Overview</a>
	</div>
	<div class="menuitem">
	<a href="plan/internal-xhtml.html">Internal XHTML</a>
	</div>
	</div>
	<div class="menuitem">
	<a href="todo.html">Todo</a>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Best Practices and Procedures</div>
	<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
	<div class="menuitem">
	<a href="howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
	</div>
	<div class="menupage">
	<div class="menupagetitle">Forrestbot svn</div>
	</div>
	<div class="menuitem">
	<a href="howto-forrestbot-scp.html" title="Publish documentation with Forrestbot scp workstage">Forrestbot scp</a>
	</div>
	<div class="menuitem">
	<a href="subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
	</div>
	<div class="menuitem">
	<a href="documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
	</div>
	<div class="menuitem">
	<a href="howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
	</div>
	<div onclick="SwitchMenu('menu_1.3.7', 'skin/')" id="menu_1.3.7Title" class="menutitle">Committer notes</div>
	<div id="menu_1.3.7" class="menuitemgroup">
	<div class="menuitem">
	<a href="zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
	</div>
	<div class="menuitem">
	<a href="procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
	</div>
	<div class="menuitem">
	<a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest Website">Publishing Forrest documentation</a>
	</div>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
	<div id="menu_1.4" class="menuitemgroup">
	<div class="menuitem">
	<a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
	</div>
	</div>
	<div id="credit"></div>
	<div id="roundbottom">
	<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
	<!--+
	\|alternative credits
	+-->
	<div id="credit2">
	<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
	</div>
	</div>
	<!--+
	\|end Menu
	+-->
	<!--+
	\|start content
	+-->
	<div id="content">
	<div class="trail">Font size:
	<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
	<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
	<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
	</div>
	<h1>How to deploy documentation with the Forrestbot "svn" workstage</h1>
	<div id="front-matter">
	<div class="abstract">
	This How-To describes the building and deployment of a documentation set
	with the help of the forrestbot "svn" workstage.
	</div>
	<div id="minitoc-area">
	<ul class="minitoc">
	<li>
	<a href="#Intended-Audience">Intended Audience</a>
	</li>
	<li>
	<a href="#Purpose">Purpose</a>
	</li>
	<li>
	<a href="#Prerequisites">Prerequisites</a>
	</li>
	<li>
	<a href="#Steps">Steps</a>
	<ul class="minitoc">
	<li>
	<a href="#introduction">Introduction</a>
	</li>
	<li>
	<a href="#follow">Follow along on your local system</a>
	</li>
	<li>
	<a href="#settings">The deploy.svn.settings file</a>
	</li>
	<li>
	<a href="#buildfile">The Forrestbot buildfile</a>
	</li>
	<li>
	<a href="#build">The "build" workstage</a>
	</li>
	<li>
	<a href="#deploy">The "deploy" workstage</a>
	</li>
	<li>
	<a href="#production">Moving the documents into production</a>
	</li>
	</ul>
	</li>
	<li>
	<a href="#faqs">Frequently Asked Questions</a>
	<ul class="minitoc">
	<li>
	<a href="#faq-general">1 General issues</a>
	<ul class="minitoc">
	<li>
	<a href="#1.1+Why+all+the+svn+warnings+about+%22is+already+under+version+control%22">1.1 Why all the svn warnings about "is already under version control"</a>
	</li>
	<li>
	<a href="#1.2+Why+are+there+SVN+diffs+for+some+documents%2C+even+though+they+have+not+changed%3F">1.2 Why are there SVN diffs for some documents, even though they have not changed?</a>
	</li>
	<li>
	<a href="#1.3+Why+is+every+PDF+document+being+deployed%2C+even+though+they+have+not+changed.">1.3 Why is every PDF document being deployed, even though they have not changed.</a>
	</li>
	</ul>
	</li>
	</ul>
	</li>
	<li>
	<a href="#Further-Reading">Further Reading</a>
	</li>
	</ul>
	</div>
	</div>
	<a name="Intended-Audience"></a>
	<h2 class="underlined_10">Intended Audience</h2>
	<div class="section">
	<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>
	</div>
	<a name="Purpose"></a>
	<h2 class="underlined_10">Purpose</h2>
	<div class="section">
	<p>
	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>
	</div>
	<a name="Prerequisites"></a>
	<h2 class="underlined_10">Prerequisites</h2>
	<div class="section">
	<p>
	Refer to the <a href="tools/forrestbot.html">Forrestbot</a> documentation.
	It is not necessary to have thorough knowledge, but a basic understanding
	will help.
	</p>
	</div>
	<a name="Steps"></a>
	<h2 class="underlined_10">Steps</h2>
	<div class="section">
	<a name="introduction"></a>
	<h3 class="underlined_5">Introduction</h3>
	<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>
	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>
	<a name="follow"></a>
	<h3 class="underlined_5">Follow along on your local system</h3>
	<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>
	<a name="settings"></a>
	<h3 class="underlined_5">The deploy.svn.settings file</h3>
	<p>
	As explained in the above document,
	if your "svn username" is different from your local system username
	create <span class="codefrag">$FORREST_HOME/deploy.svn.settings</span> file like:
	</p>
	<pre class="code"><?xml version="1.0"?>
	<project>
	<property name="deploy.svn.user" value="myApacheUsername"/>
	</project></pre>
	<a name="buildfile"></a>
	<h3 class="underlined_5">The Forrestbot buildfile</h3>
	<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="tools/forrestbot.html">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>
	<pre class="code"><?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></pre>
	<p>
	So it gets the sources relative to the current directory. Actually
	it reads the <span class="codefrag">forrest.properties</span> 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>
	<a name="build"></a>
	<h3 class="underlined_5">The "build" workstage</h3>
	<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>
	<pre class="code">cd $FORREST_HOME/site-author
	forrest -f publish.xml build</pre>
	<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 <span class="codefrag">build/forrest-docs</span> directory.
	</p>
	<a name="deploy"></a>
	<h3 class="underlined_5">The "deploy" workstage</h3>
	<p>
	When satisfied, then deploy the built docs:
	</p>
	<pre class="code">forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"</pre>
	<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>
	<a name="production"></a>
	<h3 class="underlined_5">Moving the documents into production</h3>
	<p>
	Next a cron job on the server will automatically publish it.
	However, if quicker turnaround is required, then do this:
	</p>
	<pre class="code">ssh people.apache.org
	cd /www/forrest.apache.org
	umask 002
	svn update</pre>
	<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>
	</div>
	<a name="faqs"></a>
	<h2 class="underlined_10">Frequently Asked Questions</h2>
	<div class="section">
	<a name="faq-general"></a>
	<h3 class="underlined_5">1 General issues</h3>
	<a name="1.1+Why+all+the+svn+warnings+about+%22is+already+under+version+control%22"></a>
	<h4>1.1 Why all the svn warnings about "is already under version control"</h4>
	<p>
	The deploy workstage does 'svn add' for all the generated documents
	that are new - in these cases the normal "A" messages will be issued.
	However it just blindly adds all documents that are either new or
	changed. So the warning messages are issued for the existing, updated
	documents.
	</p>
	<a name="1.2+Why+are+there+SVN+diffs+for+some+documents%2C+even+though+they+have+not+changed%3F"></a>
	<h4>1.2 Why are there SVN diffs for some documents, even though they have not changed?</h4>
	<p>
	These un-necessary differences happen because the comitter who did 'svn add' for those files
	did not have their Subversion client configured properly for the "svn:eol-style" setting.
	See some <a href="tasks.html#subversion-monitoring">notes</a>
	about rectifying this issue.
	</p>
	<a name="1.3+Why+is+every+PDF+document+being+deployed%2C+even+though+they+have+not+changed."></a>
	<h4>1.3 Why is every PDF document being deployed, even though they have not changed.</h4>
	<p>
	The PDF plugins FOP library is automatically adding a datestamp to
	every generated document. We need to find a solution.
	See <a href="https://issues.apache.org/jira/browse/FOR-1077">FOR-1077</a>
	and the <a href="docs_0_90/upgrading_09.html">Upgrading 09</a> document.
	</p>
	</div>
	<a name="Further-Reading"></a>
	<h2 class="underlined_10">Further Reading</h2>
	<div class="section">
	<ul>

	<li>
	<a href="howto-forrestbot-scp.html">How to deploy documentation with the Forrestbot "scp" workstage</a>
	</li>

	<li>
	<a href="tools/forrestbot.html">Forrestbot - automated building and deploying</a>
	</li>

	</ul>
	</div>
	</div>
	<!--+
	\|end content
	+-->
	<div class="clearboth"> </div>
	</div>
	<div id="footer">
	<!--+
	\|start bottomstrip
	+-->
	<div class="lastmodified">
	<script type="text/javascript"><!--
	document.write("Last Published: " + document.lastModified);
	// --></script>
	</div>
	<div class="copyright">
	Copyright ©
	2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
	<br>
	Apache, Apache Forrest, the Apache feather logo, and the Apache Forrest
	logos are trademarks of The Apache Software Foundation.
	</div>
	<!--+
	\|end bottomstrip
	+-->
	</div>
	</body>
	</html>