From Fedora Project Wiki

Fedora Websites Contributor Guide

This guide explains how to get access to Fedora's website code, and provides a brief overview of how to make some simple changes and commit them.

Fedora Account System

Firstly, in order to make any changes a Fedora account that has been sponsored in the web group is needed. Visit the Fedora Account System to sign up for a new account, or to apply for membership of the web group.

Sponsorship is required for an application to the web group to be successful. It is not likely that an application will be successful if the applicant is not known, so send an introductory message to the fedora-websites-list or visit the #fedora-websites IRC channel on freenode.irc.org. A great way to get sponsored is to come with a patch ready-made, which can be done by checking out a copy of Fedora's websites anonymously which will be covered next.

Checking Out Fedora's Websites

The Websites Team uses the git revision control system to store all code and is stored on Fedora Hosted.

The following steps will describe how to setup a local copy of the Fedora Websites git repository. The first step is to install git:

yum install git

The next step is to clone a copy of the git repository. This can either be done anonymously or as a registered user once an application to the web group in FAS has been successful. The code can be cloned anonymously using this command:

git clone http://git.fedorahosted.org/git/fedora-web.git

This can be done as a registered user via SSH using this command:

git clone ssh://<fas-username>@git.fedorahosted.org/git-fedora-web.git

Once this is done, a new folder, fedora-web, is created in the current working directory and contains all of the parts that make up Fedora's Websites.

After the initial clone, git-pull can be used instead that will only retrieve changes that have been made since the last update.

fedora-web Directory Structure

The top-level fedora-web folder contains individual folders for each of the sites that the Fedora Websites team looks after in this manner. For now, we'll simply examine the fedoraproject.org folder, where the files for the main project site are kept.

In this folder, you'll find 10 new files and folders:

build: contains all of the bits that compile Fedora's websites together. For most day to day changes you can safely ignore this.

ChangeLog: is a changelog. You should update this file everytime you make a change to the website so everyone knows what you did.

data: contains all of the content for the website, including template files, css, images etc.

httpd: is used by the Makefile to allow you to test your branch of the website locally.

mediawiki: is related to Fedora's wiki, and for the purposes of this guide can be ignored.

po: is used by l10n for translations etc. Again, for the purposes of this guide can be ignored.

README: contains useful information about the build scripts and how the websites work.

static: contains all the images, css and javascript that the websites use.

Updating An Existing Page Or Creating a New One

To make a change to an existing page, or update a new one you're going to need to edit the content under the data/ directory.

If the change you want to make is to a common element on multiple pages, such as the header, footer or sidebar, then use the files in the template folder. You'll notice that the majority of the code is basic HTML, but there are a few strange pieces of markup. The most obvious is $Markup(_(' that proceeds any text string. Provided you preceed any text strings that require translation with this, and close these strings with '))} then you'll have no problems. If you'd like more information about this code, I'd suggest reading the Genshi documentation.

If the change you want is to an individual page, then you'll need the files in the content folder. The same markup rules as above apply, and besides that you can edit these as you normally would. If you'd like to create a new page, I suggest using an existing file as a template and renaming it to the title of the page you want to create.

Reviewing Your Changes

To see what your changes look like live, change to the fedoraproject.org root directory and run the make command. This will build the website from the template files. It can take the <lang> option, which will create output only in the specified language rather than all the available options.

The following dependencies are required for make to complete succesfully:

Babel python-babel python-feedparser

Once the make is finished, you can run make test and point your web browser at localhost:5000 to see your local version of the Fedora website. Run make stoptest when you are finished to stop httpd.

Commiting Your Changes

To commit your changes back to your local git repository, you'll need to run the following commands:

git-add <name_of_changed_file>

for each of the files you've changed

git-commit

for this command, you'll need to provie a comment describing your changes.

Once you've done this, you'll need to put your git repository in a publically accesbile place so that others can review your changes. Your fedorapeople.org space is perfect for this. The command below will make this work:

scp -r fedora-web <fas-username>@fedorapeople.org

Now, let people know about your repository and ask them to review your changes for inclusion in the live branch.