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.
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.
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.
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.