Websites guide

[Jonathan Roberts]

Hey all,

following my experiences from this afternoon - thanks all for the
help :) - I've put together this quick guide. I think docs will hate me
for it because it doesn't follow the style-guide at all, but it's a
draft and I'll fix that later (I swear!).

The content is accurate, I think, but probably needs re-arranging and
re-phrasing because I'm not making lots of sense tonight.

Thoughts and feedback are welcome, but I think this is a pretty
important document to get right as we try to expand the team :)

Best,

Jon

------------------------------------------------

= 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 you will need a Fedora account and
to apply to and be sponsored for the web group. Visit
http://admin.fedoraproject.org/accounts/home/ to sign up for a new
account, or if you already have one to apply for the web group.

To be given membership in the web groupp existing member will have to
sponsor you. We're not likely to sponsor you if we don't know you, so
send an introductory message to the list or visit us at #fedora-websites
on freenode.irc.org. A really great way to get sponsored is to come with
a patch ready-made, and you can do this by checking out a copy of
Fedora's websites anonymously, which we'll cover next. 

== Checking Out Fedora's Websites ==

The Websites Team uses the git revision control system to store all our
code, and it is stored on fedorahosted.org. 

To get a local git repository set-up, the first thing you'll need to do
is install git:

yum install git

Next, you'll want to check out a copy of the code. You can do this
either annonymously or as a registered user once you have been sponsored
in the web team and set up your ssh key. 

To check out the code anonymously use this command:

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

To do this using ssh use this command:

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

Once this is done, you'll have a fedora-web folder containing all of the
files that create Fedora's websites.

After the initial clone, you'll be able to use git pull instead, which
will only retrieve changes that have been made since you last updated.

== 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 accessible 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 on list or in IRC and ask
them to review your changes for inclusion in the live branch.