incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject cvs commit: incubator/site/incubation Incubation_Policy.cwiki
Date Sat, 11 Sep 2004 06:19:03 GMT
crossley    2004/09/10 23:19:02

  Modified:    .        README.txt
               site     site.xml howtoparticipate.xml
               site/incubation Incubation_Policy.cwiki
  Log:
  Enhance the website production instructions.
  
  Revision  Changes    Path
  1.6       +9 -16     incubator/README.txt
  
  Index: README.txt
  ===================================================================
  RCS file: /home/cvs/incubator/README.txt,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- README.txt	10 Sep 2004 08:16:28 -0000	1.5
  +++ README.txt	11 Sep 2004 06:19:02 -0000	1.6
  @@ -21,25 +21,18 @@
   Website Howto
   =============
   
  -To generate the website one needs to install Apache Forrest
  -http://forrest.apache.org/ (use the current development version from SVN).
  +The top-level Incubator website is currently generated by Apache Forrest
  +http://forrest.apache.org/ (using the current development version from SVN).
   
  -Editors can edit the pages without generating the site, and just validate the
  -xml with a validating editor before committing. For the wiki pages it's plain
  -text, so it's easier. People with Forrest installed can build and update
  -the website. (Later the Forrestbot will take care of doing builds.)
  -
  -Anyway, do this ...
  +The source documents are in the "incubator" CVS module. Most documents are
  +in site/*.xml format. The status reports for each project are in
  +site/project/*.cwiki (this is the simple JSPWiki format).
   
  - Follow the Forrest instructions to build it
  - and set the environment variables FORREST_HOME and PATH
  +Editors can edit the pages without generating the site, and just validate the
  +xml with a validating editor before committing. For the wiki pages it is plain
  +text (therefore no validation, so be careful).
   
  - Get or update "incubator" from CVS
  - cd into the local "incubator" top-level CVS dir
  - Do 'forrest run'
  - Point the browser to http://localhost:8888/ to see the site
  - Edit the docs *in place* and see changes in the browser by reloading.
  - To generate the full website use the command-line mode 'forrest'.
  +See the document http://incubator.apache.org/howtoparticipate.html#website
   
   Subproject Website Howto
   ========================
  
  
  
  1.43      +3 -3      incubator/site/site.xml
  
  Index: site.xml
  ===================================================================
  RCS file: /home/cvs/incubator/site/site.xml,v
  retrieving revision 1.42
  retrieving revision 1.43
  diff -u -r1.42 -r1.43
  --- site.xml	11 Sep 2004 01:30:15 -0000	1.42
  +++ site.xml	11 Sep 2004 06:19:02 -0000	1.43
  @@ -94,9 +94,9 @@
           <grants href="#grants"/>
         </licenses>
         <projects>
  -        <xml>
  -          <forrest href="http://xml.apache.org/forrest/"/>
  -        </xml>
  +        <forrest href="http://forrest.apache.org/">
  +          <build href="build.html"/>
  +        </forrest>
         </projects>
         <cvs>
           <incubator>
  
  
  
  1.4       +150 -108  incubator/site/howtoparticipate.xml
  
  Index: howtoparticipate.xml
  ===================================================================
  RCS file: /home/cvs/incubator/site/howtoparticipate.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- howtoparticipate.xml	10 Sep 2004 11:08:12 -0000	1.3
  +++ howtoparticipate.xml	11 Sep 2004 06:19:02 -0000	1.4
  @@ -79,123 +79,165 @@
   	         </ul>
   	      </section>
           </section>
  -        <section>
  -         <title>Updating the site</title>
  -         
  -           <p>To generate the website one needs to get 
  -              <link href="ext:apache/projects/xml/forrest">Apache Forrest</link>
and install it.</p>
  -                
  -           <p>Editors can edit the pages without generating the site, and just validate
the
  -              xml with a validating editor before committing. For the wiki pages it's plain
  -              text, so it's easier. Ones with Forrest installed (currently nicolaken) and
  -              after the Forrestbot will take care of doing builds, fixing eventual errors
  -              and updating the site.
  -            </p>  
  -         
  -         <p>In any case, if someone wants to check the look of the pages, do this:</p>
  -
  -	      <section>
  -	         <title>Download Forrest</title>
  -	         <!-- nicolaken: currently (20031112) CVS version os needed -->
  -	         <!--<p>Download
  -	         <link href="Apache Forrest!http://xml.apache.org/forrest/.html">Apache
Forrest!http://xml.apache.org/forrest/</link>-->
  -	         <p>Download and install CVS <link href="ext:apache/projects/xml/forrest">Apache
Forrest</link>.</p>
  -	         <ul>
  -	           <li>get or update xml-forrest from CVS</li>
  - 	           <li>run the build script</li>
  - 	           <li>set FORREST_HOME to point to the build/dist/shbat</li>
  - 	           <li>add build/dist/shbat/bin to the PATH</li>
  - 	         </ul>
  - 	         <p>Example:</p>
  -<source><![CDATA[   
  -  export CVSROOT=:pserver:anoncvs@cvs.apache.org:/home/cvspublic
  -
  -  cvs login
  -  (press enter)
  -  cvs checkout xml-forrest
  -
  -  cd xml-forrest
  -  ./build.sh
  -
  -  export FORREST_HOME=`pwd`/build/dist/shbat:$PATH
  -  export PATH=`pwd`/build/dist/shbat/bin:$PATH]]>
  -	         </source>
  -	      </section>
   
  -	      <section>
  -	         <title>Download incubator</title>
  -	
  -	         <p>Download the 
  -	         <code>incubator</code> CVS module. <code>incubator</code>
contains the main Incubator site sources,
  -	         the incubator-site the final site contents.</p>
  -	         
  -	         <ul>
  -	           <li>get or update "incubator" from CVS</li>
  -	         </ul>
  -	         
  -	         <p>Continuing from the previous example:</p>
  -	
  -<source><![CDATA[ 
  -  cd ..
  -  cvs checkout incubator
  -  cvs checkout incubator-site
  -]]>  
  -</source>
  -	      </section>
  -	
  -	      <section>
  -	         <title>Make your changes</title>
  -	           
  -	         <p>Edit the XML docs in <code>incubator/site/</code>. If you
are not familiar with DTDs, 
  -	         the syntax is best learned 
  -	         <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/documentation/content/xdocs/document-v11.xml?rev=HEAD&amp;amp;content-type=text/xml.html">
  -	         by example</link>.</p>
  -	
  -	         <p>From the Forrest site, 
  -	         <link href="http://xml.apache.org/forrest/document-v12.html">here is quite
a complete example of the xml format</link>
  -	         , and 
  -	         <link href="http://xml.apache.org/forrest/wiki-sample.html">here of the
wiki format</link>.</p>
  +        <section id="website">
  +          <title>Updating the site</title>
  +          <p>This section describes how to maintain the top-level Incubator
  +            website (including the project status reports).
  +            For actual project websites see the
  +            <link href="#project-website">Project Website Howto</link> below.
  +            However, this section is still relevant for projects.
  +          </p>
  +
  +	        <section id="website-overview">
  +	          <title>Overview</title>
  +            <p>The top-level Incubator website is currently generated by
  +              <link href="ext:apache/projects/forrest">Apache Forrest</link>.
  +            </p>
  +            <p>The source documents are kept in the "incubator" CVS module.
  +            Most documents are in site/*.xml format. The status reports for
  +            each project are in site/project/*.cwiki (this is the simple JSPWiki
  +            format).
  +            </p>
  +            <p>
  +            The production documents are kept in the "incubator-site" CVS module.
  +            That module is then checked-out on the server to re-create the website.
  +            </p>
  +	        </section>
  +
  +	        <section id="website-edit">
  +	          <title>Edit the content</title>
  +            <p>People with commit access to the "incubator" CVS can edit the
  +            source documents in the "site/" directory. Anyone else can send
  +            patches to those documents.</p>
  +            <p>When editing the xml source, please ensure xml validation.
  +            When editing the simple JSPWiki source, please take care to use
  +            the correct syntax.
  +	          Here are examples of the document structures:
  +	          <link href="http://forrest.apache.org/docs/document-v12.html">xml format</link>
  +	          and 
  +	          <link href="http://forrest.apache.org/docs/wiki-sample.html">JSPWiki format</link>.</p>
  +            <p>You can just commit the source changes and leave it to someone
  +            else to generate the website.
  +            </p>
  +	        </section>
  +
  +	        <section id="website-generate">
  +	          <title>Generate the production documents</title>
  +            <p>Either install Apache Forrest locally so that you can edit and
  +            review documents immediately, or use the production system on
  +            the server to generate and copy to a staging site to view them.
  +            In the future there will be automated generation and staging systems.
  +            </p>
  +            <p>Lets explain the server-side method first, then go on to explain
  +             how to set up a local Forrest system.
  +            </p>
  +            <p>People with access to the server can use an installation of
  +              Forrest on minotaur ...
  +            </p>
  +<source><![CDATA[ssh www.apache.org
  +cd ~crossley/incubator-site
  +bash
  +bin/stage incubator
  +... This will do 'cvs checkout' of "incubator" CVS and build docs with Forrest.
  +
  +cp -R staging/incubator.apache.org ~/public_html
  +... This will copy the production to your committer webspace for viewing.
  +
  +diff -rq staging/incubator.apache.org modules/incubator-site/build/site \
  + | grep -v CVS > diff
  +vi diff
  +... Ensure that the differences are what you expect.
  +
  +cvs -q update -Pd modules/incubator-site
  +cp -Rf staging/incubator.apache.org/* modules/incubator-site/build/site
  +... Now do the usual CVS stuff: 'cvs update' 'cvs add' 'cvs diff' cvs commit'
  +
  +cd /www/incubator.apache.org
  +cvs update -Pd
  +]]></source>
  +	        </section>
  +
  +	        <section id="forrest">
  +	          <title>Using a local Forrest installation</title>
  +            <p>
  +              Install the current development version of Forrest from SVN.
  +              Follow the
  +              <link href="ext:apache/projects/forrest/build">installation</link>
  +              instructions to build it and set the environment variables
  +              $FORREST_HOME and $PATH.
  +            </p>
  +            <p>
  +              Checkout the incubator CVS modules. The site source files are kept
  +              in the "incubator" CVS at "site/". The final website contents are
  +              kept in the "incubator-site" CVS at "build/site/".
  +            </p>
  +           
  +	         <p>Edit the docs in the <code>incubator/site/</code> directory.</p>
  +	
  +	         <p>Here are examples of the document structures:
  +	         <link href="http://forrest.apache.org/docs/document-v12.html">xml format</link>
  +	         and 
  +	         <link href="http://forrest.apache.org/docs/wiki-sample.html">JSPWiki format</link>.</p>
   	
   	         <p>If you add a new page or change a page's name, update 
  -	         <code>site.xml</code>, from which the menu is generated. More details
can be found 
  -	         <link href="http://xml.apache.org/forrest/your-project.html">in Forrest's
documentation</link>.</p>
  +	         <code>site/site.xml</code> from which the menu is generated.
  +           More details can be found in the 
  +	         <link href="http://forrest.apache.org/docs/">Forrest documentation</link>.</p>
   
  -	         <p>In essence:</p>
  +	         <p>Here is a quick tour:</p>
   	         <ul>
  -	 	       <li>cd into the local "incubator" CVS dir</li>
  - 	           <li>execute "forrest run"</li>
  - 	           <li>point the browser to http://localhost:8888/ to see the site</li>
  - 	           <li>edit the docs <strong>in place</strong> and see changes
in the browser by reloading the page</li>
  - 	         </ul>  
  -	      </section>
  -	
  -	      <section>
  -	         <title>Render the site</title>
  -	         <p>In the <code>incubator</code>; directory, type 'forrest'
to render the HTML and PDF 
  -	         files in <code>build/site</code>. Forrest validates the XML, so will
catch any syntax errors.</p>
  -	         <p>Do this only if you are going to update the site yourself. If not, sumple
use a validating
  -	         parser and commit the changes or send the patch.</p>
  -	         <p>You can also simply validate docs without rendering doing a</p>
  -	         <source>  forrest validate</source> 
  -	         
  -	         
  -	      </section>
  -	
  -	      <section>
  -	         <title>Submit or commit the change</title>
  -	         <p>If the site built without errors, you have to synch the <code>incubator/build/site</code>
  -	           dir with <code>incubator-site/build/site</code>. To do this you
can use the <code>build.xml</code>
  -	           script by invoking Ant</p>
  -	           <source>  ant </source>
  +	 	       <li>cd into the local "incubator" CVS dir.</li>
  + 	         <li>Do 'forrest run'.</li>
  + 	         <li>Browser http://localhost:8888/ to review the site.</li>
  + 	         <li>Edit the docs <strong>in place</strong> at <code>site/*.*</code>
  +           and see changes in the browser by re-loading the page.</li>
  + 	         </ul>
  +
  +           <p>When you are satisifed, you will rebuild the whole site and
  +           add the changed documents to the "incubator-site" CVS.
  +           </p>
  +
  +	         <p>In the "<code>incubator</code>" directory, do 'forrest'
to
  +           render the HTML and PDF files into "<code>build/site</code>".
  +           Forrest validates the XML, so will catch any syntax errors.
  +	         You can also simply validate the source xdocs without rendering
  +           by doing 'forrest validate'.</p>
  +
  +	         <p>If the site built without errors, you now need to synch the
  +           <code>incubator/build/site</code> directory with the
  +           <code>incubator-site/build/site</code> directory.</p>
  +           <source>
  +diff -rq incubator/build/site incubator-site/build/site 
  +... Ensure that the differences are what you expect.
  +cp -Rf incubator/build/site/* incubator-site/build/site
  +... Now do the usual CVS stuff: 'cvs update' 'cvs add' 'cvs diff' cvs commit'
  +           </source>
  +
  +           <p>Another way to do this is to use the <code>build.xml</code>
  +	         script by invoking Ant "syncsite" task. Do 'ant' in the top-level
  +           "incubator" directory.</p>
   	         
  -	         <p>You can now make a patch with the command 
  -	         <code>cvs diff -u &gt; incubator-site.diff</code> in the <code>incubator-site/</code>
  -	          directory, and submit it to the mailing list, starting with '<code>[PATCH]</code>'
in the email subject.</p>
  -	
  -	         <p>Incubator committers can just commit the contents of <code>build/site</code>
(after checking it is okay!).</p>
  +	         <p>If you are not an Incubator committer, then you can now make a
  +           patch with the command 
  +	         '<code>cvs diff -u &gt; incubator-site.diff</code>' in the
  +           "<code>incubator-site/</code>" directory, and submit it to the
  +           mailing list, starting with '<code>[PATCH]</code>' in the email
  +           subject.</p>
  +	
  +	         <p>Incubator committers can just commit the contents of
  +           <code>incubator-site/build/site</code> (after checking it is okay!).
  +           Then publish the website on the server.
  +           </p>
  +           <source>
  +ssh www.apache.org
  +cd /www/incubator.apache.org
  +cvs update -Pd
  +           </source>
   	      </section>
           </section>
         </section>
  +
         <section id="project">
            <title>Project-specific resources</title>
            <p>Some <link href="site:projects">projects</link> under incubation
have their own mailing lists, 
  
  
  
  1.10      +6 -5      incubator/site/incubation/Incubation_Policy.cwiki
  
  Index: Incubation_Policy.cwiki
  ===================================================================
  RCS file: /home/cvs/incubator/site/incubation/Incubation_Policy.cwiki,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- Incubation_Policy.cwiki	21 Jun 2004 09:29:09 -0000	1.9
  +++ Incubation_Policy.cwiki	11 Sep 2004 06:19:02 -0000	1.10
  @@ -182,17 +182,18 @@
   {{{         /www/incubator.apache.org/projectname
   }}}
   
  -{{/www/incubator.apache.org/projectname}} has to be checked out of CVS.  We don't care
how it gets into CVS, or which CVS module it lives in, but it had better be there.
  +To create the website, the directory {{/www/incubator.apache.org/projectname}} is checked
out of CVS.  We don't care how it gets into CVS, or which CVS module it lives in, but it had
better be there.
   
  -People using Maven, ForrestBot, or any other tool still have to address the CVS publishing
requirement that the infrastructure team has laid out.  If that is done, then we just run
cvs up in that directory to load the site from CVS.
  +People using Maven, ForrestBot, or any other tool still have to address the CVS publishing
requirement that the infrastructure team has laid out.  If that is done, then we just run
"cvs update" in that directory to load the site from CVS.
   
  -The Mentors MUST add the information about the CVS module and dir where the published site
is, in the project incubation status file.
  +The Mentors MUST add the information to the project incubation status file, to
  +descibe the CVS module and the directory which holds the published site.
   
  -If the project does not want to host the published site in their CVS, it has a space under:
  +If the project does not want to host the published site in their project CVS, it has a
space under:
   {{{        incubator-site/build/site/projectname/**
   }}}
   
  -The site is automatically updated from there once a day.
  +The site is automatically updated from CVS once a day.
   
   !!!Exitting the Incubator
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org


Mime
View raw message