forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: rev 55607 - forrest/trunk/src/documentation/content/xdocs
Date Tue, 26 Oct 2004 13:29:42 GMT
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/"/>

Mime
View raw message