Contribute

Webmastering

The Web team maintain and develop the FSFE's websites — ranging from fsfe.org to project and campaign sites. Webmasters are volunteers working to enhance the organization's face to the world, and to improve the technical solutions of our web efforts.

Get to know us, get to know the website

If you want to get an idea of what work on FSFE's website consists of, the best way is to come have a chat with us. Some of the webmasters are regularly on freenode's #fsfe channel, where we will be happy to meet you and answer your questions! To check out who is working on the website, and with FSFE as a whole, visit our team page.

Your web coordinators, Nicolas Jean and Andreas Tolf Tolfsen.

Introduction

The technologies and programs used to maintain the FSFE web page should already be familiar to many developers and authors and might be of interest to those that have not yet discovered them.

Translators and occasional volunteers will most likely only get in touch with

  • XHTML – from which the web pages are generated
  • Subversion – for version control of web page sources
  • Trac – for access permission management, issue tracking and other related services.

Volunteers interested in getting deeper into the maintenance should also be familiar with

  • Perl – for the maintenance and page creation scripts
  • Apache – as the web server

Understanding how the web pages are built

The web pages of fsfe.org are maintaned as a set of XML files. The web server generates the HTML pages from these XML files automatically every ten minutes. Consequently, all editing of the pages is done in the XML files, and the HTML is never edited directly.

Every page on fsfe.org is named pagename.language.html (language being the two-letter ISO-639 code of the language, like "en" for English or "de" for German). The source files are named pagename.language.xhtml.

Some pages have a dynamic part: apart from the fixed texts taken from the XHTML file, they include information from one or several XML files. Whenever such a page is built, the build system takes the translated XML files where available, and falls back to the English version of those XML files that have not yet been translated. This way, such pages can end up with parts of the text being translated and other parts still showing in English. Examples of such pages include the start page, the news page, and the events page.

Getting access to the web pages

The source files for the web pages are stored on the fsfe-web subversion repository, hosted on the FSFE subversion server. Other services are available on the related trac instance.

To have access to these tools, just follow these instructions:

  • If you are a Fellow of the FSFE you already have read access to subversion and trac, just log in with your usual Fellowship username and password.

  • Everyone else can register a guest account for the subversion and trac, using the web form at https://trac.fsfe.org/fsfe-web/register. As soon as you register, you'll have read access to the subversion repository and you can log into the trac site (please note that a guest- prefix will be added to the username you choose).

To have write access to the subversion repository, and the trac wiki and ticket system, just write to system-hackers@fsfeurope.org

Checking out a SVN branch to work on

The subversion repository has two main code bases for the FSFE website, the SVN trunk, which is used to build the production instance of the website at http://fsfe.org/, and the test branch, which is used to build http://test.fsfe.org/.

For day-to-day work, like adding news items, translating pages (or even developing small changes to the website) you will need to check out the SVN trunk:

svn --username YOUR_FELLOWSHIP_NAME co https://svn.fsfe.org/fsfe-web/trunk

To work on major changes to the website, including debugging new features that could potentially break the site, you are encouraged to check out the test branch of the SVN repository:

svn --username YOUR_FELLOWSHIP_NAME co https://svn.fsfe.org/fsfe-web/branches/test

Please note that a full working copy will require about 160M; if you only plan to work on part of the website, you can check out only the directories that you are interested in. You can browse the SVN tree online to find out what you are interested in.

To checkout the Document Freedom Day SVN, use:

svn --username YOUR_FELLOWSHIP_NAME co https://svn.fsfe.org/df-web/trunk

Working with the repository

In subversion, keyword substitution must be enabled explicitely on every file. Since we use some keywords on .xml and .xhtml files (for example the $Author$ keyword on the page footer), you should automate enabling keywords adding the following snippet to your ~/.subversion/config file:

    enable-auto-props = yes

    [auto-props]
    *.xml = svn:keywords=Date Author Id Revision;svn:mime-type=text/xml;svn:eol-style=native
    *.xhtml = svn:keywords=Date Author Id Revision;svn:mime-type=text/xhtml;svn:eol-style=native
        

After you checked out the repository the first time, you should execute

svn update

every time before you work on a specific file.

If you want to add new files or directories to the repository you have to execute

svn add filename

To enable keyword substitution for a new file, execute

svn propset svn:keywords "Date Author Id Revision" filename

To post your changes to the server, no matter be it a new file or a modification in an existing file, execute

svn commit filename

and your default editor will open to allow for some description of your changes.

If you are used to work with CVS, you will easily start working with SVN; as you have noticed, the basic commands are very similar. To learn more, you can see an overview of the differences between CVS and SVN at Subversion for CVS Users, and a quick reference comparison of CVS and SVN commands at CVS to SVN Crossover Guide

You can download a detailed manual for SVN at the Subversion book page (we are using the 1.5 release of SVN).

Coordination tools

The work on the website pages is coordinated on the Webmasters mailing list.

The fsfe-web trac instance provides some further tools to help coordination: a SVN repository web browser, an issue tracking system and a wiki.

You can find out more about using trac at the TracGuide wiki page.

If you want to keep track with all commits that are done to the web page sources, you can also subscribe to the commit notification mailing list and you will get a mail for every change posted to the source tree.

Responsible handling of write access

If you have write access to the web pages, please subscribe to the Webmasters mailing list.

Please bear in mind that all your changes will become effective and visible automatically, without any further action of anybody. Consequently, there are a few things we would request you to do whenever you commit changes or new files:

  • The FSFE is held responsible for the content of the web pages. Please do not commit modifications that change the meaning of the text without approval from a core team member of the FSFE. (This is not necessary for translations of already existing content.)

  • If you are posting translations, and there is any chance that others can proofread it, use that chance. You can use the Translators mailing list to ask for proofreading. Whether you are translating files or proofreading them, you are encouraged to spell-check files using some automated tools, such as GNU aspell, ispell, or your favourite spell-checker. For example, to use GNU aspell on a Debian GNU/Linux system, just install the packages aspell and aspell-XX (where "XX" is your language code), then run the command

    aspell -H -d language -c file.xhtml

    where "language" is the name of the dictionary for your language; the -d option can be omitted if your UNIX locale is the same as the language of the dictionary).

  • Make sure that all files are proper XML. By default, the SVN server will check the XML syntax of files with .xml and .xhtml extensions, and will forbid the commit if XML errors are found. To avoid this, you can check your files before committing them, in one of the following ways.

    There is a script named /trunk/tools/validate.pl that helps finding errors in the markup. Improper XML breaks the automatic build process of the web pages and blocks updates for the complete FSFE website. If you suspect the build process to broken, you can view the log of the last build run on our status pages.

    The validate.pl script requires the XML::LibXML Perl module; if this is not installed on your system, you can validate files using your favourite XML validator. For example you can use the command line xmllint utility from the libxml2 project.

    If you are using the Debian GNU/Linux distribution, install the libxml2-utils package; run the command

    xmllint --noout file.xhtml

    where file specifies the file you want checked, and watch for possible error messages.

  • Make sure the encoding of the file is consistent with the content of the "encoding" attribute declared in the first line of the file. For example, if your file is encoded as "UTF-8" , the first line of the file should read

    <?xml version="1.0" encoding="UTF-8" ?>

    If you want to change the encoding of a file, you can use the standard iconv utility, as in the following example (which converts a file from the "latin1" to the "UTF-8" encoding):

    iconv -f LATIN1 -t UTF8 inputfile > outputfile

Please coordinate with other people who also have SVN commit access to make sure that translations and fixes contributed by people without commit access are committed properly after they have been proofread. Of course, please check these files before you commit them like you check your own files.

Licensing of Source Code

Whenever you introduce either server side program code (i.e. PHP, Perl) or java script code to the website, please make sure you comply with our licensing policies. Specifically this means:

  • When writing scripts on behalf of FSFE, please put them under AGPLv3+ (That is AGPL 3.0 with the addition "or any later version")
  • When introducing scripts from 3rd parties, please make sure they are under a Free Software License listed on http://www.gnu.org/licenses/license-list.html
  • When you write scripts for FSFE (but are not employed by FSFE) we would prefer to have the script licensed under AGPLv3+, GPLv3+, LGPLv3+, Apache 2.0 or CC0, licensing the code under a Free Software License is mandatory for FSFE in order to deploy it.

Use custom licensed media

If you use images or other media which which has been licensed using a Creative Commons license or another license, you can make sure that the proper licensing information is displayed by adding these at the end of the document before </html>. Here are three examples:


    <legal type="cc-license">
      <license>https://creativecommons.org/licenses/by-sa/3.0/</license>
      <notice>This work is published under the Creative Commons BY-SA 3.0 Unported license by John Doe</notice>
    </legal>


    <legal>
      <license>http://www.gnu.org/licenses/fdl-1.3.txt</license>
      <notice>This page is published under the GNU Free Documentation License 1.3 or later</notice>
    </legal>

    <legal>
      <notice>This work is published undere the CC-BY-SA 3.0 Unported license or the <a href="http://artlibre.org/">Licence Art Libre 1.3</a> at your option, etc.</notice>
    </legal>


        

Other FSFE websites

Besides the main fsfe.org website, volunteers are welcome to contribute to other FSFE and Fellowship websites; you can find more information about these on the FSFE wiki.