Project Guidelines

The xml.apache.org Project Guidelines

This document defines the guidelines of the xml.apache.org project. It includes definitions of the various categories of membership, who is able to vote, how conflicts are resolved by voting, and the procedures to follow for proposing and making changes to the codebase of the Project.

Note that our sister project, jakarta.apache.org, is formulating a number of other project-wide guidelines that the xml community may wish to copy or modify. In Sept-2001 there are also a number of discussions on the general@xml.apache.org and commons-dev@xml.apache.org mailing lists about other cross-project guidelines that we hope will standardize our projects and make developing and using them easier. Stay tuned!

This is a living document. Changes can be made by the Project Management Committee.

Roles and Responsibilities Defines the recognized roles in the project.
Communication Defines how users and developers communicate.
Decision Making Defines how action items are proposed and voted on.
Source Repositories Defines how the Project's source code is organized and developed.
Project Management Defines the roles and responsibilities of the Project Management Committee (PMC).
Our Mission / Charter A copy of the Charter document for the xml.apache.org Project.

Website update guidelines

As XML-oriented projects, so our website is also generated from XML files. While many similar websites may use servlets or a system like Cocoon to generate their websites on-the-fly from XML documents, we currently checkin source .xml files of the documentation and then generate a static set of .html files for most of this website.

While each subproject's individual areas may be managed separately (by that subproject's committers) the top-level of the website must be managed through the "site" repository. Thus to change any of the files at the root of http://xml.apache.org/ you would first check out the "site" repository from svn.apache.org

ForrestBot "publish" Step-by-Step

We're using ForrestBot for build and deploy the XML website. ForrestBot comes with Apache Forrest 0.8 (install forrest and set FORREST_HOME and PATH as described below). The root directory of your XML site checkout contains the file "publish.xml" which is an Ant build file that manages the build and the deployment of the XML website. Please look into this file for further instructions to set up ForrestBot on your machine. Basically, we're simply using ForrestBot manually by typing "forrest -f publish.xml" after we're happy with our changes to the site. Step-by-step instructions for the deployment process again:

Modify the sources of the website and check locally with Forrest 0.8 (e.g. do "forrest run").
Once you're satisfied, do "forrest -f publish.xml" to do a clean build of the website. If the build completes without problems, the website will be uploaded to the Subversion repository at https://svn.apache.org/repos/asf/xml/site/targets/.

Using a Local Forrest

To use a local Forrest (during website development, not for deployment):

Due to bug FOR-555 we cannot use the latest Forrest release. Please download the forrest_07_branch branch (http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch).
set environment variable FORREST_HOME=~ (where ~ is the directory where Forrest is installed) (see http://forrest.apache.org/docs/your-project.html for details)
set environment variable PATH=$PATH:$FORREST_HOME/bin
cd to your local XML site checkout
update your local XML site checkout (svn update)
do 'forrest run' and view localhost:8888, or do 'forrest' which will build the web-site documents in build/site for local viewing.

You can use "forrest run" to start a local web server. That improves development speed as you can simply refresh in the browser after a change. Point your browser to http://localhost:8888/ to review the site in this case.

Deleting Documentation Files

ForrestBot simply uploads the whole generated site. It doesn't delete obsolete files. You can do that manually in the /www/xml.apache.org/ folder on cvs.apache.org. Be careful when doing stuff like that.

Please make sure you always have group rw permissions on all files under the /www directory!

Updating Forrest based sub-project websites

The sub-projects generate their website from their own sources and put the result into the relevant project directory, i.e. /xml/site/targets/[your-project]/

To use Forrest for your project install it as described, then cd in the directory of your project and run "forrest". Publish the HTML/PDF result of the build into the xml-site/targets module (copy the results of ./build/site/ to /xml/site/targets/your-project/ and commit changes). The sources of the top-level xml.apache.org website are in the /xml/site/src/documentation/ directory.

Updating non-Forrest sub-project websites

To update a part of the website (that does *not* use Forrest) do this:
Checkout the /xml/site module (you only actually need a few subdirs, but the whole thing is quite large).
Make updates to your .xml files in the /xml/site/sources/your-project directory.
Go to the /xml/site/sources directory locally and run the relevant shell or bat script.
Check that the .html structure in your local targets directory is built correctly.
Checkin to SVN both your updated sources/ and targets/ trees as needed,
Either login to cvs.apache.org and cd to /www/xml.apache.org and do an update of directories there as needed,
Or send an email to infrastructure<at>apache.org and ask for your website to be added to the cronjob for automatic update.