Gnome Games - Developer's Guidelines

These are step-by-step instructions about how to contribute to Gnome Games. These assume you are just starting to contribute to GNOME development, regulars should already have found this out. Most of these instructions also apply to other GNOME modules.

I've got this great idea !

You may have some new graphics, a new feature, or a bug fix. Depending on what it is you should do different things.

• Graphics and Sounds - submit these as a bug report in Bugzilla. Be warned that the size of Gnome Games is already quite large and we are quite picky about what we include, so don't feel bad if your contribution is rejected. Another frequent occurrence is that the maintainer will ask for changes, this may hurt your pride, but it is also a sign that he wants to include it. He should tell you why he wants the changes. Do not submit graphics or sounds unless you are certain of their copyright status. Ideally it should be your own work. SVG graphics should be as clean as possible, make sure to clear out unused defines and if using Inkscape to save as Plain SVG. If you want to contribute a new card theme for aisleriot, see this link for more information about the card theme format.

• Patches - whether for bug fixes or enhancements, send these to Bugzilla. Details on how you should make patches can be found below. The list of bugreports is a very good starting point for finding bugs which need to be fixed. Everybody loves a bugfixer!

• Major Enhancements and Features - ultimately are treated like patches, but you should also discuss them on the mailing list before-hand since their integration into Gnome Games will require co-ordination. This will also prevent duplication of effort.

• Suggestions - Suggestions come in many forms. Specific feature requests and user-interface criticism should go into Bugzilla, often with the severity "enhancement". Ideas which are vague or far-reaching should be discussed on the mailing list.

• New Games - Gnome Games is a very large package and there is neither the room for new games or the time to maintain them. Therefore no new games will be accepted into Gnome Games. (Note that this does not apply to Aisleriot where we welcome requests for, and patches adding, new solitaire variants. Just file a bug for it.) However we can help you with advice on how to let your game make the most of GNOME technologies. Just ask on the mailing list.

I want to help, any suggestions ?

If you want to help out, but don't have a great new idea of your own, then we have plenty for you. The two major sources are the the TODO file in the top of the Gnome Games distribution and the list of open bugs in bugzilla. To avoid conflicts with two people working on the same thing, if it looks like it will take more than a small amount of effort then drop a line to the mailing list describing your intentions.

Gnome games is always looking to improve usability and accessibility, which can include tasks such as new themes or making it easier to use games using the keyboard. Multiplayer network gaming is another long term goal for anyone interested in a challenge. Porting to other platforms, making games scalable and ensuring the user interface works well on smaller screens is also worth keeping in mind. Documentation and translation are always needed too.

Once you have your idea, you can proceed as above. If you are fixing a bug or implementing a feature requested in a bug report then the best place to send your code is as a patch at the end of the relevant bug report.

Most contact should be through the mailing list or bugzilla. If, for some reason, you need to contact the maintainer directly the MAINTAINERS file in the gnome-games distribution has the name and email address of the current maintainers.

Getting the code

Obviously you need some code to work with. You can work with the latest tarballs from the FTP site but this is not recommended since they get out of date quickly. The best option is to use Git. There are two options: either update your entire GNOME system from Git using something like Jhbuild or only download Gnome Games from Git. jhbuild is comprehensive and guaranteed to keep you up to date. Unfortunately it takes a lot of time and disk space and often keeps you too close to the bleeding edge. If you only download the gnome-games module you will have to take care of dependencies yourself.

The best solution depends on what you want to do. If you want to keep up with all the latest GNOME work then a full development build is best. If you only want to work on Gnome Games then it is best only to download the single module. To do this issue the following shell command from the directory you want to store everything in.

$ git clone git://git.gnome.org/gnome-games

Go into the gnome-games directory and type ./autogen.sh --prefix=/some/directory, this will run configure and set everything up. The directory you give should be the place you want to install the GNOME software you are going to hack on. This should not be /usr. You can use your home directory, e.g. --prefix=~/gnome/.

If you only want to work on some games, you can cut down on the dependencies using the --enable-games switch. To work on only gnometris and iagno, use --enable-games=gnometris,iagno. Search for "allgames" in configure.in to see the full list of games.

If autogen.sh complains about missing libraries or libraries that are too old then you will need to find and install appropriate versions of these libraries yourself. Usually these can be found at the GNOME FTP site. If autogen.sh dies strangely then either you haven't installed gnome-common or you need to install newer autotools. Once autogen.sh has run successfully you can type make install to build everything and install it.

For instructions to help you track your changes to the code and send them back upstream, see Git/Developers. For translation, see TranslationProject/GitHowTo.

Required library dependencies

This is the list of required software packages for gnome-games:

• GNOME 2.16.0
• GTK+ 2.8.0
• GNOME Doc Utils - gnome-doc-utils 0.10.0
• GNOME Python Desktop - gnome-python-desktop 2.17.3 (python-gnome2)
• gnome-python2-gnomeprint
• Cairo 1.0
• RSVG 2.14.0
• Guile 1.8.0
• GStreamer 0.10.11
• Python 2.4
• PyGTK - python-gtk2-dev 2.10.0
• libxml 2.4.0
• scrollkeeper
• expat
• ggz-client-libs 0.0.14
• libggz 0.0.14
• Vala 0.13

These packages are optional, but highly recommended:

• SDL_Mixer 1.2.0 or later for sound support using SDL.
• gtkglext 1.2.0 , pygtkglext 1.1.0 and pyopengl 2.0 for 3D support in Chess.
• ggz-server 0.0.14 for hosting GGZ servers.

To compile these packages, we recommend using the baseline GNOME 2.18.x development packages. While gnome-games may compile with older versions, we will not accept bug reports for games used under those conditions.

• GStreamer 0.10 is required by gnome-games, and is used to play sounds.
• SDL_Mixer is also supported for playing sounds.

CVS checkouts will require the latest intltool.In addition it is useful to have a working C++ compiler (e.g. g++, part of the gcc suite) and the guile implementation of the Scheme programming language version 1.6 or later (http://www.gnu.org/software/guile/guile.html). If either of these is missing then the games that rely on them will simply not be built.

glChess can optionally take advantage of Python OpenGL and GtkGLExt to render the board using 3D OpenGl. glChess supports any CECP compatible AI, such as crafty or gnuchess. See the README file in the glchess directory for more information about glChess and it's optional software dependencies.

The included gnuchess AI can be run using the 'gnome-gnuchess' binary. To compile glChess without the bundled gnuchess binary, you can compile with ./configure --disable-gnuchess

The games that require additional packages are:

• guile scheme: Aisleriot
• C++: Blackjack, Gnometris
• Python: glchess, gnome-sudoku

Finding your way around

Now you've got the code, you need to find the bit you want to alter. All the games are in individual subdirectories. There is also a subdirectory of library code called libgames-support. The directory name po is for translations. Some subdirectories are split into further src and data subdirectories.

Each game has a distinct structure, but there are several common file types beyond the normal .c and .h files.

• .schemas.in - These files contain gconf keys.

• .desktop - Files that describe menu entries.

• help/* - The help files. These are written in docbook and are read by yelp. For English speakers the C subdirectory is probably what you want.

Style

Gnome Games uses the GNU Coding Style, which is described in the HACKING file in the source distribution. There is also a script called indent.sh in the source distribution which automatically indents the source code correctly for you. New patches to Gnome Games will have to use the GNU Coding Style consitently.

For issues of user-interface style you should refer to the Human Interface Guidelines.

Choices of algorithm and technique are of course up to you, but remember that the programs have to run on a wide variety of hardware: Slow and fast, 32-bit and 64-bit, little-endian and big-endian. There is also a wide variety of operating systems. Use glib macros and utility functions instead of libc ones where possible, glib has already solved most of the cross-platform problems for you.

Internationalization

All GNOME programs are internationalized so they can be easily translated into other languages. Doing this requires special care when using strings that will be presented to the user. Often this is as simple as placing _( ) around these strings. However there are a few catches and if in doubt you should refer to the document Internationalising GNOME Applications. For example you should not construct sentences from individual pieces, what works in English often doesn't work in other languages.

Sending Your Changes Upstream

To show your changes to others, you will need to generate a patch file. If you have made commits, use the git format-patch command. Otherwise, use git diff. (See Git/Developers for more detailed information on using Git.)

If you generate a patch without using Git, then try and use the "unified" format. For diff use the -u switch.

When you are happy with your changes, you should send a patch to the maintainer to be reviewed and hopefully applied. The usual way to do this is to attach it to a bug report using the "Create New Attachment" link.

Once he has received it, the maintainer will have to have a look at your patch and decide whether he wants to apply it. Usually he does, but sometimes changes need to be made. The time it takes to apply the patch depends on both how busy the maintainer is and what code freezes are in place. Code freezes are used to stabilize the code before a major release and mean that only bugs are fixed, new features are not added. In that case the patch will be deferred until the next development cycle. The best time for large pieces of code is at the beginning of a development cycle, usually a week or so after a major GNOME release (e.g. 2.6.0).

People who consistently post good quality patches are given direct access to the GNOME Git server so they can do it themselves.

Translating Documents

WARNING: These instructions are outdated and need to be updated since we now use GNOME Doc Utils.

The help files that accompany the games also need translating. If your language isn't supported, and you would like to help, here are some hints:

What you must do

• Get the sources as explained above.

• From the gnome-games source directory, go to your_game/help. if a your_language_code directory exists, go to it (you language code is generally a two letters code, like "fr" for French). Otherwise create it. copy the C directory to your_language_code. Inside are all the xml files you must translate.

• Edit them with your favorite text or XML editor.

• Open them with the command yelp <filename> to check what you've done.

• When everything is done, submit it as a patch on bugzilla as explained on this page.
• Warning : Some terms in the English rules aren't accurate. Please fix them in the English rules when you find some. Post these fixes to bugzilla too. If in doubt about the meaning of a phrase, feel free to ask the maintainers for an explanation.

What you should do

It is best that you do these things, but if you get confused the maintainer can help you.

• Rename your_game-C.omf to your_game-your_language_code.omf and translate it.

• In "your_game/help/you_language_code", edit the file "Makefile.am", and change, "lang = C omffile = your_game-C.omf", replacing C on each of these lines with your language code.

• From the gnome-games source directory, edit the file configure.in, find the AC_CONFIG_FILES variable (near the end of the file) and add the line your_game/help/you_language_code/Makefile.

Suggestions

• Edit the files use a good XML editor. Features such as color syntax highlighting help you avoid making mistakes. One suitable editor is bluefish, most popular code editors also have XML modes.
• Keep in mind that uniformity helps users quickly learn new games. Keep the everthing consistent.

• For aisleriot, start with aisleriot.xml, then definitions.xml (glossary), to set up the appropriate main terms in your language, so you can use them everywhere after that. This will bring speed and uniformity to your translation.

• Try to always translate the same concepts with the same sentences in your language.
• Copy and paste as much as you can to avoid mispelling and to enhance uniformity, but take care of slight differences. Also make sure the first version is error free, you don't want to be correcting a mistake you have pasted into ten different places.

• The translation and documentation have more resources.