Page History

There is a separate SVN directory for the website. It's built using Apache Forrest.

Setup environment

Checkout the website

This is based on Apache MRUnit's instructions. The website uses the Apache CMS. More detailed documentation is available on the Apache Infrastructure pages including a quickstart guide on the Apache bookmarklet and a reference manual. It is also useful to look at other Apache CMS sites for examples.

Process

1. Commit a change to the website's source Markdown files located in https

...

1. ://svn.apache.org/repos/asf/hive/cms/trunk. Before committing test that the site

...

Setup Apache Forrest

At the time of this writing the Apache Forrest project is distributed as two tar files, one sources and one dependencies. You need both of this files. Here is how I installed it:

$ tar -zxvf apache-forrest-0.9-sources.tar.gz
$ tar -zxvf apache-forrest-0.9-dependencies.tar.gz
$ mv apache-forrest-0.9 /usr/local/
$ export FORREST_HOME=/usr/local/apache-forrest-0.9/
$ export PATH=$PATH:$FORREST_HOME/bin

Contribute a patch

Make some changes

$ vim author/src/documentation/path/to/somefile.xml # (make some change)
$ svn add author/src/documentation/path/to/somefile.xml (add some file)

Build the site

$ ant

If the build was a success you should be able to preview the changes via the local publish/ directory in your browser. The output will contain PDF's which don't work well with patches. Therefore we will revert the publish/ directory to create a patch which can then be reviewed.

$ svn revert -R publish/

Create a patch

$ svn diff > /tmp/HIVE-XXXX.patch

Commit a patch

$ cd hive-site
$ patch -p0 --dry-run < /tmp/HIVE-XXXX.path
$ patch -p0 < /tmp/HIVE-XXXX.path
$ ant

If the build was a success you should be able to preview the changes via the local publish/ directory in your browser. If the output looks good you can commit it:

1. still builds locally by installing the CMS build scripts and running:

   buildsite/build_site.pl --source-base hive-site --target-base hive-website
   

   If deleting a file or changing the name of a file make a trivial edit to lib/path.pm or lib/view.pm to force a full site rebuild. If making a simple edit it is easier to just use the Apache bookmarklet.

2. Wait a few minutes to get the email on the commits list that buildbot has rebuilt the staging website.

3. If the change looks ok, commit the change to the production website by one of the following:

   • Using the Apache bookmarklet and selecting Publish site
   • curl -sL http://s.apache.org/cms-cli | perl on your local machine
   • ssh -t <user>@people.apache.org publish.pl mrunit <your Apache ID>

Posting generated content

1. Add the path to content/extpaths.txt relative to the extpaths.txt file to prevent the content getting deleted when the staging site is published
2. Commit the generated content directly to the production site svn

Style

• Try to limit line length to 80 columns, fold -s <filename> on Linux is helpful for limiting line length
• Use links in the [link name][] style rather than [link name][1] because it is more difficult to match up the numbers and removing links causes all the numbers to have to get updated
• Indent with spaces not tabs
• Use * for lists and indent lists by 2 spaces

...