nicolaken 2003/11/12 02:55:08
Modified: build/site howtoparticipate.pdf howtoparticipate.html
Log:
New and improved docs about how to participate.
Revision Changes Path
1.3 +314 -210 incubator-site/build/site/howtoparticipate.pdf
<<Binary file>>
1.3 +199 -94 incubator-site/build/site/howtoparticipate.html
Index: howtoparticipate.html
===================================================================
RCS file: /home/cvs/incubator-site/build/site/howtoparticipate.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- howtoparticipate.html 6 Nov 2003 16:41:37 -0000 1.2
+++ howtoparticipate.html 12 Nov 2003 10:55:08 -0000 1.3
@@ -2,7 +2,7 @@
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>howtoparticipate</title>
+<title>How to Participate</title>
<link type="text/css" href="skin/page.css" rel="stylesheet">
</head>
<body text="#000000" bgcolor="#FFFFFF">
@@ -222,7 +222,7 @@
<table class="title" summary="">
<tr>
<td valign="middle">
-<h1>howtoparticipate</h1>
+<h1>How to Participate</h1>
</td><script language="Javascript" type="text/javascript">
function printit() {
if (window.print) {
@@ -249,150 +249,255 @@
</table>
<ul class="minitoc">
<li>
-<a href="#How+to+Participate">How to Participate</a>
+<a href="#Check+this+first">Check this first</a>
</li>
<li>
-<a href="#Project-specific+resources">Project-specific resources</a>
-</li>
+<a href="#Incubator+Project+resources">Incubator Project resources</a>
+<ul class="minitoc">
<li>
<a href="#Mailing+lists">Mailing lists</a>
</li>
<li>
-<a href="#general%40incubator.apache.org">[email protected]</a>
-</li>
-<li>
-<a href="#projects%40incubator.apache.org">[EMAIL PROTECTED]</a>
-</li>
-<li>
-<a href="#cvs%40incubator.apache.org">[EMAIL PROTECTED]</a>
-</li>
-<li>
-<a href="#announce%40incubator.apache.org">[EMAIL PROTECTED]</a>
-</li>
-<li>
-<a href="#pmc%40incubator.apache.org">[EMAIL PROTECTED]</a>
-</li>
-<li>
<a href="#Updating+the+site">Updating the site</a>
</li>
-<li>
-<a href="#Download+Forrest">Download Forrest</a>
-</li>
-<li>
-<a href="#Download+incubator-site">Download incubator-site</a>
+</ul>
</li>
<li>
-<a href="#Make+your+changes">Make your changes</a>
-</li>
+<a href="#Project-specific+resources">Project-specific resources</a>
+<ul class="minitoc">
<li>
-<a href="#Render+the+site">Render the site</a>
+<a href="#Subproject+Website+Howto">Subproject Website Howto</a>
</li>
-<li>
-<a href="#Submit+or+commit+the+change">Submit or commit the change</a>
+</ul>
</li>
</ul>
-<a name="N10007"></a><a name="How+to+Participate"></a>
-<h3>How to Participate</h3>
-<div style="margin-left: 0 ; border: 2px">
-<p>
-<strong>TODO</strong>: Need to add all Incubator project resources here</p>
-</div>
-<a name="N1000F"></a><a name="Project-specific+resources"></a>
-<h3>Project-specific resources</h3>
-<div style="margin-left: 0 ; border: 2px">
-<p>Some projects under incubation have their own mailing lists, or their
development discussion occurs on the mailing list of another project. Check out
the project websites to be sure what mailing list is the right one.</p>
-</div>
-<a name="N10015"></a><a name="Mailing+lists"></a>
-<h3>Mailing lists</h3>
-<div style="margin-left: 0 ; border: 2px">
-<p>As with everything else in Apache, most of what goes on happens or is
discussed on electronic mailing lists. Here are the lists associated with this
project, and their purposes:</p>
-</div>
-<a name="N1001B"></a><a name="general%40incubator.apache.org"></a>
-<h3>[email protected]</h3>
-<div style="margin-left: 0 ; border: 2px">
-<p>This is where general and public discussion of things about the project
take place. It's also where follow-up messages sent in reply to cvs commit
reports get sent (see the next list). There is a 'digest' form of this list,
which collects individual messages and sends the collection when enough have
accumulated or a given amount of time has passed since the last digest. Anyone
may subscribe; only subscribers may post. </p>
+
+<a name="N1000C"></a><a name="Check+this+first"></a>
+<h3>Check this first</h3>
+<div style="margin-left: 0 ; border: 2px">
+<p>Before doing anything, we encourage you to read the incubator website and
in particular
+ our "About" documents.</p>
+<p>If you have other questions, feel free to post them on
[email protected]</p>
+<p>If you want to help in the development of a specific <a
href="projects/">Incubated Project</a>
+ refer to its development mailing list; the Incubator mailing
lists are for project
+ incubation, not development.</p>
+<p>In case of generic Project development questions, there is [EMAIL
PROTECTED]</p>
+</div>
+
+<a name="N10023"></a><a name="Incubator+Project+resources"></a>
+<h3>Incubator Project resources</h3>
+<div style="margin-left: 0 ; border: 2px">
+<div class="frame fixme">
+<div class="label">Fixme (nicolaken)</div>
+<div class="content">Check that all Incubator project resources are
listed.</div>
+</div>
+<a name="N1002D"></a><a name="Mailing+lists"></a>
+<h4>Mailing lists</h4>
+<div style="margin-left: 0 ; border: 2px">
+<p>As with everything else in Apache, most of what goes on happens or is
discussed
+ on electronic mailing lists. Here are the lists associated
with this project,
+ and their purposes.</p>
+<a name="N10036"></a><a name="general%40incubator.apache.org"></a>
+<h5>[email protected]</h5>
+<div style="margin-left: 0 ; border: 2px">
+<p>This is where general and public discussion of things about the project
+ take place. It's also where follow-up messages sent in reply
to cvs commit
+ reports get sent (see the next list). There is a 'digest'
form of this list,
+ which collects individual messages and sends the collection
when enough have
+ accumulated or a given amount of time has passed since the
last digest.
+ Anyone may subscribe; only subscribers may post.</p>
<ul>
+
<li>To subscribe, send a message to [EMAIL PROTECTED]</li>
+
<li>To subscribe to the digest, send a message to [EMAIL PROTECTED]</li>
+
<li>To unsubscribe, send a message to [EMAIL PROTECTED]</li>
+
</ul>
</div>
-<a name="N10028"></a><a name="projects%40incubator.apache.org"></a>
-<h3>[EMAIL PROTECTED]</h3>
+<a name="N1004C"></a><a name="projects%40incubator.apache.org"></a>
+<h5>[EMAIL PROTECTED]</h5>
<div style="margin-left: 0 ; border: 2px">
-<p>This is the development mailing list for some of the projects in
incubation. Anyone may subscribe; only subscribers may post. </p>
+<p>This is the development mailing list for some of the projects in
incubation.
+ Anyone may subscribe; only subscribers may post.</p>
<ul>
+
<li>To subscribe, send a message to [EMAIL PROTECTED]</li>
+
<li>To unsubscribe, send a message to [EMAIL PROTECTED]</li>
+
</ul>
</div>
-<a name="N10033"></a><a name="cvs%40incubator.apache.org"></a>
-<h3>[EMAIL PROTECTED]</h3>
+<a name="N1005F"></a><a name="cvs%40incubator.apache.org"></a>
+<h5>[EMAIL PROTECTED]</h5>
<div style="margin-left: 0 ; border: 2px">
-<p>When changes are made to the code repository, the details are
automatically sent to this list. Its Reply-To is set to the 'general' list, so
if you reply to a cvs message that's where your reply is going to end up.
Anyone may subscribe; only subscribers may post. </p>
+<p>When changes are made to the code repository, the details are
automatically sent to this list. Its Reply-To is set to the 'general' list, so
if you reply to a cvs message that's where your reply is going to end up.
Anyone may subscribe; only subscribers may post.</p>
<ul>
+
<li>To subscribe, send a message to [EMAIL PROTECTED]</li>
+
<li>To unsubscribe, send a message to [EMAIL PROTECTED]</li>
+
</ul>
</div>
-<a name="N1003E"></a><a name="announce%40incubator.apache.org"></a>
-<h3>[EMAIL PROTECTED]</h3>
+<a name="N10072"></a><a name="announce%40incubator.apache.org"></a>
+<h5>[EMAIL PROTECTED]</h5>
<div style="margin-left: 0 ; border: 2px">
-<p>This is the list to which you should be subscribed if you want to be kept
apprised of significant events or milestones in the project's activities, but
don't want to track the full traffic in the 'general' list. Anyone may
subscribe; all posts are moderated. </p>
+<p>This is the list to which you should be subscribed if you want to be kept
+ apprised of significant events or milestones in the
project's activities, but
+ don't want to track the full traffic in the 'general' list.
Anyone may subscribe;
+ all posts are moderated.</p>
<ul>
+
<li>To subscribe, send a message to [EMAIL PROTECTED]</li>
+
<li>To unsubscribe, send a message to [EMAIL PROTECTED]</li>
+
</ul>
</div>
-<a name="N10049"></a><a name="pmc%40incubator.apache.org"></a>
-<h3>[EMAIL PROTECTED]</h3>
+<a name="N10085"></a><a name="pmc%40incubator.apache.org"></a>
+<h5>[EMAIL PROTECTED]</h5>
<div style="margin-left: 0 ; border: 2px">
<ul>
+
<li>This is a private list for the project management committee. It is not
open to general subscription.</li>
+
</ul>
</div>
-<a name="N10050"></a><a name="Updating+the+site"></a>
-<h3>Updating the site</h3>
-<div style="margin-left: 0 ; border: 2px">
-<p>The process for submitting new documentation or modifying an existing
page is as follows.</p>
</div>
-<a name="N10056"></a><a name="Download+Forrest"></a>
-<h3>Download Forrest</h3>
+<a name="N10093"></a><a name="Updating+the+site"></a>
+<h4>Updating the site</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>Download <a href="Apache
Forrest!http://xml.apache.org/forrest/.html";>Apache
Forrest!http://xml.apache.org/forrest/</a>, or obtain it from CVS: </p>
-<pre class="code"> export CVSROOT=:pserver:[EMAIL
PROTECTED]:/home/cvspublic
- cvs login
- (press enter)
- cvs checkout xml-forrest
- cd xml-forrest
- ./build.sh
- export PATH=`pwd`/build/dist/shbat/bin:$PATH</pre>
-</div>
-<a name="N10062"></a><a name="Download+incubator-site"></a>
-<h3>Download incubator-site</h3>
+<p>To generate the website one needs to get
+ <a href="http://xml.apache.org/forrest/";>Apache Forrest</a>
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>
+<a name="N100A6"></a><a name="Download+Forrest"></a>
+<h5>Download Forrest</h5>
<div style="margin-left: 0 ; border: 2px">
-<p>Download the <span class="codefrag">incubator-site</span>CVS module.
Continuing from the previous example: </p>
-<pre class="code"> cd ..
- cvs checkout incubator-site</pre>
+<p>Download and install CVS <a href="http://xml.apache.org/forrest/";>Apache
Forrest</a>.</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>
+<pre class="code">
+ export CVSROOT=:pserver:[EMAIL PROTECTED]:/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
+ </pre>
+</div>
+<a name="N100CF"></a><a name="Download+incubator"></a>
+<h5>Download incubator</h5>
+<div style="margin-left: 0 ; border: 2px">
+<p>Download the
+ <span class="codefrag">incubator</span> CVS module. <span
class="codefrag">incubator</span> 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>
+<pre class="code">
+ cd ..
+ cvs checkout incubator
+ cvs checkout incubator-site
+
+</pre>
</div>
-<a name="N1006D"></a><a name="Make+your+changes"></a>
-<h3>Make your changes</h3>
+<a name="N100ED"></a><a name="Make+your+changes"></a>
+<h5>Make your changes</h5>
<div style="margin-left: 0 ; border: 2px">
-<p>Edit the XML docs in
<code>incubator-site/src/documentation/content/xdocs/</code>. If
you are not familiar with DTDs, the syntax is best learned <a
href="href=%22http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/documentation/content/xdocs/document-v11.xml?rev=HEAD&content-type=text/xml.html";>by
example</a>.</p>
-<p>From the Forrest site, <a
href="http://xml.apache.org/forrest/document-v12.html";>here is quite a complete
example of the xml format</a>, and <a
href="http://xml.apache.org/forrest/wiki-sample.html";>here of the wiki
format</a>.</p>
-<p>If you add a new page or change a page's name, update <span
class="codefrag">site.xml</span>, from which the menu is generated. More
details can be found <a
href="http://xml.apache.org/forrest/your-project.html";>in Forrest's
documentation</a>.</p>
+<p>Edit the XML docs in <span class="codefrag">incubator/site/</span>. If
you are not familiar with DTDs,
+ the syntax is best learned
+ <a
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/documentation/content/xdocs/document-v11.xml?rev=HEAD&content-type=text/xml.html";>
+ by example</a>.</p>
+<p>From the Forrest site,
+ <a href="http://xml.apache.org/forrest/document-v12.html";>here
is quite a complete example of the xml format</a>
+ , and
+ <a href="http://xml.apache.org/forrest/wiki-sample.html";>here
of the wiki format</a>.</p>
+<p>If you add a new page or change a page's name, update
+ <span class="codefrag">site.xml</span>, from which the menu is
generated. More details can be found
+ <a href="http://xml.apache.org/forrest/your-project.html";>in
Forrest's documentation</a>.</p>
+<p>In essence:</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>
</div>
-<a name="N1008A"></a><a name="Render+the+site"></a>
-<h3>Render the site</h3>
+<a name="N10128"></a><a name="Render+the+site"></a>
+<h5>Render the site</h5>
<div style="margin-left: 0 ; border: 2px">
-<p>In the <code>incubator-site/</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>In the <span class="codefrag">incubator</span>; directory, type 'forrest'
to render the HTML and PDF
+ files in <span class="codefrag">build/site</span>. 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>
+<pre class="code"> forrest validate</pre>
+</div>
+<a name="N10143"></a><a name="Submit+or+commit+the+change"></a>
+<h5>Submit or commit the change</h5>
+<div style="margin-left: 0 ; border: 2px">
+<p>If the site built without errors, you have to synch the <span
class="codefrag">incubator/build/site</span>
+ dir with <span
class="codefrag">incubator-site/build/site</span>. To do this you can use the
<span class="codefrag">build.xml</span>
+ script by invoking Ant</p>
+<pre class="code"> ant </pre>
+<p>You can now make a patch with the command
+ <span class="codefrag">cvs diff -u >
incubator-site.diff</span> in the <span class="codefrag">incubator-site/</span>
+ directory, and submit it to the mailing list, starting with
'<span class="codefrag">[PATCH]</span>' in the email subject.</p>
+<p>Incubator committers can just commit the contents of <span
class="codefrag">build/site</span> (after checking it is okay!).</p>
+</div>
</div>
-<a name="N10090"></a><a name="Submit+or+commit+the+change"></a>
-<h3>Submit or commit the change</h3>
-<div style="margin-left: 0 ; border: 2px">
-<p>If the site built without errors, you can now make a patch with the
command <code>cvs diff -u > incubator-site.diff</code> in the
<code>incubator-site/</code> directory, and submit it to the
mailing list, 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>
</div>
+
+<a name="N1016F"></a><a name="Project-specific+resources"></a>
+<h3>Project-specific resources</h3>
+<div style="margin-left: 0 ; border: 2px">
+<p>Some <a href="projects/">projects</a> under incubation have their own
mailing lists,
+ or their development discussion occurs on the mailing list of
another project. Check out
+ the project websites to be sure what mailing list is the right
one.</p>
+<a name="N1017C"></a><a name="Subproject+Website+Howto"></a>
+<h4>Subproject Website Howto</h4>
+<div style="margin-left: 0 ; border: 2px">
+<p>Do not use the "incubator" CVS module for project docs, but the module of
+ the specific project.</p>
+<p>Check-in the generated pages in the "incubator-site" CVS module under
+<span
class="codefrag">\incubator-site\build\site\projects\${project-name}\**</span>.</p>
+<p>When the site is updated from CVS (it's once a day) it will be live.</p>
+</div>
+</div>
+
+
+
<div class="attribution"></div>
</div>
</td><td width="10"><img width="10" height="1" alt=""
src="skin/images/spacer.gif" class="spacer"></td>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
