Difference between revisions of "Editing audacityteam.org"
(How to update the website from changes in CVS.)
Revision as of 13:50, 19 October 2008
This page describes the process in place to make changes to the main audacity website on http://audacity.sourceforge.net/. This process requires that you have a sourceforge account and are listed as a developer on the audacity project.
How the site works
In order to make the site available in many languages, we use PHP and the GNU gettext tools to deliver one set of pages translated into many languages. This makes it possible to update all language versions of the website with minimal effort. Text that has not yet been translated into a given language will appear in English until the translation is updated.
The site has a single set of PHP pages which contain the English version of the pages. All text that appears on the screen is stored as PHP strings (rather than using included HTML) and output using =, echo etc. These strings are marked for translation by enclosing them in brackets preceded by an underscore.
When the pages are altered, xgettext is used to go through all the .php pages on the site and construct a message catalogue of all the strings marked as needing translation. Duplicates and known standard strings (dates etc) are removed at this point to create audacity_website.pot, which is the translation template. A copy of this template exists for every language the website is translated into, named after the ISO language code with a .po extension (so fr.po, de.po etc). These contain all the strings marked for translation and the translation into that language of the string. These files are maintained and updated by the team of audacity translators for each language.
Once translations have been obtained, they are compiled using msgfmt to create message catalogue files (*.mo files) for each language. When a page from the web site is set to a visitor, the web server reads the relevant .mo file, looks up each string, and sends the translated text to the user instead of the English version.
Editing the website
Audacity keeps the PHP source to it's web site in CVS. So to edit the website you need to check out a working copy of the website source from the htdocs module in CVS. You can then edit the relevant page, and commit you changes back to CVS. At this point, nothing has changed on the web server, but the new version of the site has been stored in CVS.
Updating the web server from CVS
The copy of the web site that users actually see is located on a web server run by Sourceforge in Chicago. In order for changes in CVS to become visible, they need to be transmitted to that server. This process currently works on *nix-like systems (such as Linux, or Mac OS X if you use the command line tools) only.
You will need all of the following installed on the system you use to update the web site. Note that at this point you are not actually editing anything, so a remote shell login to a system is quite sufficient.
- CVS. Fairly obvious, importantly your copy of CVS must check out files with CR line endings, as on a Unix system. CVS for Windows does not do this.
- SSH. Needed as a transport layer for both CVS and Rsync.
- Rsync. Used to transmit files to and from the sourceforge web server.
- GNU Make. Used to automate commands in the translation process. Other makes may work but have not been tested.
- GNU gettext tools. msgfmt and xgettext are needed to generate and compile translations.
- Python. Audacity uses a customised message merging tool to deal with cases where a string is not translated but a very similar one is. This is written in Python, so your system needs to be able to run .py scripts.
You will need to have developer CVS over SSH access to sourceforge set up in order to check out the current web code - see the sourceforge documentation.
Updating the site
This assumes you already have a working copy of the htdocs CVS module, and are in the top level htdocs folder.
- Set the SFUSER environment variable to your username on sourceforge, so the scripts know who to try and log in as.
- Run make pull to download files that aren't under CVS control from the web server into your file tree. This may overwrite changes to your working copy, but that doesn't matter provided that you have committed them to CVS.
- Bring your CVS working copy up to date without extraneous directories by running cvs up -P -d (you will need the password for your SSH key).
- Check the output to ensure that all version controlled files are in sync with CVS. In general if they are not then the CVS version is the correct one, so conflicting or modified files can be deleted and re-checked out (this is where subversion's revert command should be used, but CVS doesn't have one).
- Run make pretend-push to see a list of altered files that will be uploaded to the sourceforge server (you will need the password for your SSH key). If this isn't what you expected, then check what is going now. No files are actually changed at this point.
- Run make to create first audacity_website.pot, then update the .po files with the new strings, then compile all the .po files into .mo files. This can take a while and be quite CPU intensive.
- Run make pretend-push again. You should see that as well as the files you saw last time, locale/audacity_website.pot and all the .mo files in locale are scheduled to be uploaded to the server. No .po files will be uploaded because the rsync command ignores them (they are not needed on the web server).
- Finally run make push to upload the files.