You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2004/10/26 15:29:42 UTC
svn commit: rev 55607 - forrest/trunk/src/documentation/content/xdocs
Author: crossley
Date: Tue Oct 26 06:29:40 2004
New Revision: 55607
Added:
forrest/trunk/src/documentation/content/xdocs/proposal-asf-forrestbot.xml (contents, props changed)
forrest/trunk/src/documentation/content/xdocs/proposal-asf-publish.xml (contents, props changed)
Modified:
forrest/trunk/src/documentation/content/xdocs/site.xml
Log:
Proposal for ASF-wide documentation staging and publishing
Proposal for ASF-wide Forrestbot
Added: forrest/trunk/src/documentation/content/xdocs/proposal-asf-forrestbot.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/documentation/content/xdocs/proposal-asf-forrestbot.xml Tue Oct 26 06:29:40 2004
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+
+ Licensed 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 document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+"http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Draft: Proposal for ASF-wide Forrestbot</title>
+ </header>
+
+ <body>
+ <warning>This is a draft proposal document. It is not yet the
+ consensus of ASF nor the Infrastructure committee.
+ </warning>
+
+ <section id="overview">
+ <title>Overview</title>
+ <p>All ASF projects need to be able to concentrate on their projects
+ and the content of their websites, rather than get tangled up in
+ arcane website publication procedures.
+ </p>
+ <p>A proposal is currently being discussed for
+ <a href="proposal-asf-publish.html">ASF-wide documentation staging
+ and publishing</a>. The context of this Forrestbot proposal is at
+ Item C through to Item G of that infrastructure, the "staging server".
+ This does not preclude other mechanisms - some projects might choose
+ to use Forrestbot.
+ </p>
+ </section>
+
+ <section id="forrestbot">
+ <title>About Forrestbot</title>
+ <p>The Forrestbot enables the automated building and deployment of
+ websites. It will retrieve the source from SVN or CVS, build the
+ website, and then deploy it. Notifications can be sent. It keeps a
+ log of the build process.
+ See more <a href="site:forrestbot">detailed explanation</a>.
+ </p>
+ <p>There is also a "web interface" component to Forrestbot to enable
+ the project committers to easily trigger their website build, view
+ the result, and deploy it to the staging server.
+ See more <a href="site:forrestbot-web-interface">detailed explanation</a>.
+ </p>
+ </section>
+
+ <section id="requirements">
+ <title>Requirements</title>
+ <p>The staging server (e.g. stage.apache.org) would be a virtual server.
+ A stable version of "forrest" and "forrestbot" would be installed there.
+ Each project that uses forrestbot would have a forrestbot configuration
+ file. This defines the SVN or CVS repository to get the source from,
+ where to deploy the built site, and various other parameters.
+ </p>
+ <p>The Forrestbot web interface requires a servlet container (e.g.
+ <a href="http://jakarta.apache.org/tomcat/">Apache Tomcat</a>) and
+ an <a href="http://httpd.apache.org/">Apache HTTP Server</a> would be
+ used to view the staging sites.
+ </p>
+ </section>
+ </body>
+</document>
Added: forrest/trunk/src/documentation/content/xdocs/proposal-asf-publish.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/documentation/content/xdocs/proposal-asf-publish.xml Tue Oct 26 06:29:40 2004
@@ -0,0 +1,260 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+
+ Licensed 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 document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+"http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Draft: Proposal for ASF-wide documentation staging and publishing</title>
+ </header>
+
+ <body>
+ <warning>This is a draft proposal document. It is not yet the
+ consensus of ASF nor of the Infrastructure committee.
+ This proposal is a summary of various email discussions held
+ over the past years, especially on infrastructure@a.o
+ around 2004-07-29 which expanded on previous discussions.
+ </warning>
+
+ <section id="overview">
+ <title>Overview</title>
+ <p>All ASF projects need to be able to concentrate on their projects
+ and the content of their websites, rather than get tangled up in
+ arcane website publication procedures.
+ </p>
+ <p>There is a "staging and publishing server" which is separate
+ from the live production web server. The project committers would
+ commit their source changes, then trigger a "documentation build",
+ then review the staging website.
+ When satisfied, they "approve and publish" so as to copy the stage
+ to the "publication point". There are a number of rotated older
+ versions of the publication point. A deliberate action on the
+ live webserver causes rsync to pull the current publication point
+ into production.
+ </p>
+ </section>
+
+ <section id="infrastructure">
+ <title>Publication infrastructure and actions</title>
+ <source>
++------------------+ [<a href="#A">A</a>] Commit the changes to source documents |
+| svn.apache.org | |
+| | [<a href="#B">B</a>] +------------------------------------+ |
+| | | Source docs managed in project SVN | |
++------------------+ +------------------------------------+ V
+
++------------------+ [<a href="#C">C</a>] Trigger the build |
+| stage.apache.org | |
+| | [<a href="#D">D</a>] +---------------------+ |
+| | | Build the documents | |
+| | +---------------------+ |
+| | |
+| | [<a href="#E">E</a>] +-------------------------------+ |
+| | | Staging server enables review | |
+| | +-------------------------------+ |
+| | |
+| | [<a href="#F">F</a>] Approve and publish |
+| | |
+| | [<a href="#G">G</a>] +----------------------------+ |
+| | | Publication point | |
+| | | (with some older versions) | |
++------------------+ +----------------------------+ V
+
++------------------+ [<a href="#H">H</a>] Rsync pull into production |
+| www.apache.org | |
+| | [<a href="#I">I</a>] +--------------------------------------+ |
+| | | Production webserver $tlp.apache.org | |
++------------------+ +--------------------------------------+ V
+</source>
+
+ <section id="A">
+ <title>[A] Commit the changes to source documents</title>
+ <p>The content changes are committed to the project's source repository.
+ The committer might have already built and tested the documents with
+ their local documentation build system. On other occasions, they might
+ commit changes without building locally. Some committers might not
+ even have installed a local build system, they might just edit or
+ patch the content.
+ </p>
+ </section>
+
+ <section id="B">
+ <title>[B] Source docs are managed in project SVN</title>
+ <p>The source files for the project's website are held in an SVN
+ repository. These might be XML source for some projects, while others
+ might have simple HTML docs.
+ </p>
+ </section>
+
+ <section id="C">
+ <title>[C] Trigger the build</title>
+ <p>Via a secure https web interface, or via ssh to the server and use
+ command-line.
+ </p>
+ </section>
+
+ <section id="D">
+ <title>[D] Build the documents</title>
+ <p>The build system on the server will generate the project documents
+ and deploy them to the staging server website.
+ </p>
+ <p>
+ Projects can use various documentation tools: Anakia, Forrest, Maven,
+ raw html, etc. Each system would have its own ways to report build
+ problems to the committer (e.g. xml validation, broken links,
+ content and spelling errors, configuration errors).
+ </p>
+ </section>
+
+ <section id="E">
+ <title>[E] Staging server enables review</title>
+ <p>A pre-release website. Anyone can review online. Some projects might want to
+ password-protect.
+ </p>
+ </section>
+
+ <section id="F">
+ <title>[F] Approve and publish</title>
+ <p>When satisfied, they "approve and publish" so as to copy the stage
+ to the "publication point".
+ Via a secure https web interface, or via ssh to the server and use
+ command-line.
+ </p>
+ </section>
+
+ <section id="G">
+ <title>[G] Publication point</title>
+ <p>A holding area, from which the production website can be recreated
+ as required.
+ Keep a number of rotating versions, i.e.
+ </p>
+ <source>
+rm -rf ${publish_dir}.3
+mv ${publish_dir}.2 ${publish_dir}.3
+mv ${publish_dir}.1 ${publish_dir}.2
+mv ${publish_dir} ${publish_dir}.1
+mv $staging_dir $publish_dir
+ </source>
+ </section>
+
+ <section id="H">
+ <title>[H] Rsync pull from publication point into production</title>
+ <p>
+ Someone with commit access for the project would issue a command on
+ the live web server to synchronise with the current
+ contents of the publication server via rsync pull. This would either
+ be executed by ssh and command-line, or via a secure https web interface.
+ </p>
+ <p>
+ We want the final rsync to be independent, so that it can also be
+ executed by infrastructure people in the event that the web sites
+ need to be recreated.
+ </p>
+ <source>
+The rsync would be manual.
+
+The old way ...
+ cd /www/$tlp.apache.org; cvs up -Pd
+ or
+ cd /www/jakarta.apache.org/$proj; cvs up -Pd
+
+The new way ...
+
+ rsync -avz -e ssh --delete stage.apache.org:/www/$tlp.apache.org/ \
+ /www/$tlp.apache.org/
+ or
+ rsync -avz -e ssh --delete stage.apache.org:/www/jakarta.apache.org/$proj/ \
+ /www/jakarta.apache.org/$proj/
+ </source>
+ </section>
+
+ <section id="I">
+ <title>[I] Production webserver for the project</title>
+ <p>The live production website for the project at $tlp.apache.org
+ </p>
+ </section>
+ </section>
+
+ <section id="notes">
+ <title>Other notes</title>
+ <ul>
+ <li>The actions (A and C and F and H) are completely independent
+ manual steps and are deliberate accountable acts.
+ This ensures human oversight in the deployment process.
+ </li>
+ <li>
+ The actions should not be automated, especially action H.
+ If someone did manage to break in to the publishing server,
+ then their changes would be automatically published.
+ </li>
+ <li>Some people would like action C and action F to be automated
+ (say every 30 hours). Committers can still trigger it manually
+ at other times.
+ </li>
+ <li>The actions F and H could be combined. For example, we could have
+ a script on the production server that contacted the publishing
+ server to perform action F and then performed the rsync (action H).
+ </li>
+ <li>The proposal from Apache Forrest to have an
+ <a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
+ as one method for projects to handle the "staging server"
+ (item C through to item G).
+ This does not preclude other mechanisms.
+ </li>
+ <li>The
+ <a href="http://wiki.apache.org/cocoon/Doco">Doco</a>
+ concept adds interactive and workflow capabilities to this
+ publication infrastructure.
+ </li>
+ </ul>
+ </section>
+
+ <section id="impediments">
+ <title>Background and impediments</title>
+ <p>This is a collection of notes about the past impediments
+ which have hindered the publishing process ...
+ </p>
+ <ul>
+ <li>
+ The generated project sites were maintained in source control,
+ primarily to enable the infrastructure team to restore the live
+ web server in case of emergency. That added one more level of
+ complexity for the projects.
+ </li>
+ <li>
+ When people wanted to work on projects docs, they were hindered
+ by needing to install the document generation system locally.
+ That was too onerous for some projects and caused delays with
+ website maintenance.
+ </li>
+ </ul>
+ </section>
+
+<!--
+-->
+ <section id="scratch">
+ <title>Scratch notes</title>
+ <p>Some notes which have not yet been incorporated ...</p>
+ <source><![CDATA[
+* How would we log the actions?
+
+* Noel: We need to accomodate sites that come from a single source,
+and sites that come from multiple sources,
+e.g. Jakarta or the XML Federation.
+]]></source>
+ </section>
+ </body>
+</document>
Modified: forrest/trunk/src/documentation/content/xdocs/site.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/site.xml (original)
+++ forrest/trunk/src/documentation/content/xdocs/site.xml Tue Oct 26 06:29:40 2004
@@ -160,6 +160,11 @@
-->
</getting-involved>
+ <proposals label="Proposals" tab="project">
+ <asf-publishing label="ASF Publishing" href="proposal-asf-publish.html"/>
+ <asf-forrestbot label="ASF Forrestbot" href="proposal-asf-forrestbot.html"/>
+ </proposals>
+
<references label="Related projects">
<gump label="Apache Gump" href="http://gump.apache.org/"/>
<cocoon label="Apache Cocoon" href="http://cocoon.apache.org/"/>