User:Jonrob/WebsitesGuide

= 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, which 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-core

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 git://@git.fedorahosted.org/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 which 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 using these tools. This tutorial will examine the fedoraproject.org folder, where the files for the main project site are kept.

In this folder, there are 10 different files and folders:

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

ChangeLog: is a changelog. This file should be updated everytime a change is made to the websites' code.

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

httpd: is used by the Makefile to test the local repository in a web browser.

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 to create a new one, the content under the data/ directory needs to be edited.

If the desired change is to an element that is common to multiple pages, such as the header or footer, then use the files in the template/ folder. If the change is to an individual page, either updating an existing page or creating a new one, the files under the content/ folder need to be edited.

The files in both of these folders are mostly standard HTML markup. The only difference is the use of  that proceeds any text-string. This allows the Fedora Websites Team to use Python's gettext function for language translations, but provided this simple piece of markup proceeds any text-strings there will be no problems.

To learn more about this read the Python and Genshi documentation.

Reviewing Your Changes
Changes can be reviewed by using the  to build the website and then running a local web server such as httpd. First, change to the fedoraproject.org root directory, and then run the  command. This will build the website from the template files. It can take the  option (e.g.  ), which will create the 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, run. This will copy all of the files in the out/ directory to the httpd/ directory and make some configuration changes before starting httpd so that the website can be viewed locally. Point a web browser at http://localhost:5000 to view it.

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

git-add 

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 @fedorapeople.org:public_html

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