nicolaken 2003/11/12 02:45:31
Added: site howtoparticipate.xml
Removed: site howtoparticipate.cwiki
Log:
New and improved docs about how to partecipate.
Revision Changes Path
1.1 incubator/site/howtoparticipate.xml
Index: howtoparticipate.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>How to Participate</title>
</header>
<body>
<section>
<title>Check this first</title>
<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 <link
href="site:projects">Incubated Project</link>
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>
</section>
<section>
<title>Incubator Project resources</title>
<fixme author="nicolaken">Check that all Incubator project resources
are listed.</fixme>
<section>
<title>Mailing lists</title>
<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>
<section>
<title>[email protected]</title>
<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>
</section>
<section>
<title>[EMAIL PROTECTED]</title>
<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>
</section>
<section>
<title>[EMAIL PROTECTED]</title>
<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>
</section>
<section>
<title>[EMAIL PROTECTED]</title>
<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>
</section>
<section>
<title>[EMAIL PROTECTED]</title>
<ul>
<li>This is a private list for the project management
committee. It is not open to general subscription.</li>
</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:[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]]>
</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;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>
<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>
<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>
</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>
<p>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, 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>
</section>
</section>
</section>
<section>
<title>Project-specific resources</title>
<p>Some <link href="site:projects">projects</link> 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>
<section>
<title>Subproject Website Howto</title>
<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
<code>\incubator-site\build\site\projects\${project-name}\**</code>.</p>
<p>When the site is updated from CVS (it's once a day) it will be live.</p>
</section> </section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
