From Fedora Project Wiki
 
(7 intermediate revisions by the same user not shown)
Line 11: Line 11:
 
== Checking Out Fedora's Websites ==
 
== Checking Out Fedora's Websites ==
  
The Websites Team uses the git revision control system to store all code and is stored on [http://fedorahosted.org Fedora Hosted].  
+
The Websites Team uses the git revision control system to store all code, which is stored on [http://fedorahosted.org 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:
 
The following steps will describe how to setup a local copy of the Fedora Websites git repository. The first step is to install git:
  
<pre>yum install git</pre>
+
<pre>yum install git-core</pre>
  
 
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:
 
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:
Line 23: Line 23:
 
This can be done as a registered user via SSH using this command:
 
This can be done as a registered user via SSH using this command:
  
<pre>git clone ssh://<fas-username>@git.fedorahosted.org/git-fedora-web.git</pre>
+
<pre>git clone git://<fas-username>@git.fedorahosted.org/fedora-web.git</pre>
  
 
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.  
 
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.
+
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 ==
 
== 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.
+
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, you'll find 10 new files and folders:
+
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 you can safely ignore this.  
+
'''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. You should update this file everytime you make a change to the website so everyone knows what you did.
+
'''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, css, images etc.
+
'''data''': contains all of the content for the website, including template files and css.
  
httpd: is used by the Makefile to allow you to test your branch of the website locally.
+
'''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.  
+
'''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.
+
'''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.
+
'''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.
+
'''static''': contains all the images, css and javascript that the websites use.
  
 
== Updating An Existing Page Or Creating a New One ==
 
== 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.  
+
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 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 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.  
  
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.  
+
The files in both of these folders are mostly standard HTML markup. The only difference is the use of <code>${Markup(_('</code> 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 ==
 
== 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.  
+
Changes can be reviewed by using the <code>Makefile</code> 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 <code>make</code> command. This will build the website from the template files. It can take the <code><lang></code> option (e.g. <code>make en</code>), 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:
 
The following dependencies are required for make to complete succesfully:
  
Babel
+
babel
 +
 
 
python-babel
 
python-babel
 +
 
python-feedparser
 
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.
+
Once the make is finished, run <code>make test</code>. 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 ==
 
== Commiting Your Changes ==
Line 85: Line 89:
 
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:
 
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
+
scp -r fedora-web <fas-username>@fedorapeople.org:public_html
  
 
Now, let people know about your repository and ask them to review your changes for inclusion in the live branch.
 
Now, let people know about your repository and ask them to review your changes for inclusion in the live branch.

Latest revision as of 08:45, 29 June 2008

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://<fas-username>@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 ${Markup(_(' 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 Makefile 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 make command. This will build the website from the template files. It can take the <lang> option (e.g. make en), 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 make test. 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 <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:public_html

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