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. -- Fedora-websites-list mailing list Fedora-websites-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/fedora-websites-list
