[You can also view the single-page version of this document.]

Web Site Changes

Introduction

The Subversion project welcomes improvements to its web site. However, the process is not as simple as clicking "Save As" in a browser, editing and mailing the change. For one thing, many pages are actually composed of three or more files so browsers do not save a correctly rendered copy.

Because of this, if you're planning to submit substantial changes, we recommend that you obtain a copy of the sources and set up a testing mirror to check your changes.

Of course, for small changes, simply inspecting the patch visually will often be sufficient.

Obtaining the web site sources

The source to the website is available from a Subversion repository. To browse the sources, go to https://svn.apache.org/repos/asf/subversion/site/

To download a copy to ~/projects/svn, which is the location used for the rest of this page, use the following commands: 

  mkdir -p ~/projects/svn
  cd ~/projects/svn
  svn co https://svn.apache.org/repos/asf/subversion/site/ site

If you download to another location, you will need to adjust paths in your web server configuration to point there.

Setting up a mirror for testing

The Subversion web site uses Server Side Includes (SSI) to assemble pages within the web server. This means that to validate any changes you might wish to make, you need to view the relevant pages through a web browser connected to a server installed on your system, either Apache 2.2 or Apache 2.4.

The following steps should provide an Apache virtualhost that correctly renders a local copy of the Subversion web site on a Unix-type system. This is likely to be located under /etc/apache2, /etc/httpd or a similiar directory, depending on your system. These instructions have been tested on Apache 2.2 and Apache 2.4.

  1. Obtain the web site sources as described in the section above.
    For the purpose of the following discussion, we will assume that these are in the directory /home/user/projects/svn/site
  2. Configure an Apache server to use the site/publish directory within the working copy mentioned above as DocumentRoot for either the main server or a VirtualHost.
  3. Check your Apache server includes mod_include.so
  4. Enable Server Side Includes for the relevant DocumentRoot. The relevant Apache directive is: 
    Options +Includes
  5. Turn on SSI parsing for html files for the relevant DocumentRoot. The relevant Apache directive is: 
    AddOutputFilter INCLUDES .html

Putting it all together, an example VirtualHost configuration is:

<VirtualHost *:8080>
        ServerAdmin webmaster@localhost

        DocumentRoot /home/user/projects/svn/site/publish
        <Directory /home/user/projects/svn/site/publish/>
                Options +Includes
                AddOutputFilter INCLUDES .html
        </Directory>

        ErrorLog ${APACHE_LOG_DIR}/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel debug

        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

After restarting or reloading the server, you should see a copy of the Subversion community guide Web Changes page if you use the following link: 

http://127.0.0.1:8080/docs/community-guide/web.html#web_mirror

Validating your changes

Please validate all patches which make substantial changes to the web site.

If you have set up a mirror of the website as advised on this page, use the command line to fetch a correctly rendered copy of the page you've changed with 

wget http://127.0.0.1:8080/docs/community-guide/YOUR_CHANGED_PAGE.html

then upload the resulting file to a HTML validator, for example, W3C validator service.

Creating a patch and a log message

When writing log messages for patches regarding the project's web pages, eg: 

https://subversion.apache.org/docs/community-guide/some_page.html#section-name

list the names of files modified in the patch in the log message, relative to the site/ directory and list anchors of sections added or modified like this: 

 * docs/community-guide/some_page.html
   (section-name): fixed issue xyz

For a full discussion of the Subversion patch requirements, please follow the project general patch guidelines and log message guidelines.