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.
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.
Patches - whether for bug fixes or enhancements, send these to Bugzilla. Details on how you should make patches can be found below.
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. 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.
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.
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 maintainer.
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 SVN. There are two options for using SVN: either update your entire GNOME system from SVN using something like jhbuild or only download Gnome Games from SVN. 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 SVN 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 commands from the directory you want to store everything in.
When asked for a password just hit enter, anyone can use anonymous SVN and there is no password. When you issue each get command a long list of file names will be printed as they are downloaded. Once it is finished you will have a directory named gnome-games and a directory called gnome-common. You are almost ready.
Go into the gnome-common 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 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.
Once gnome-common is installed repeat the process in the gnome-games directory. You are now ready to begin hacking !
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.
In general you should use the same style as the files you are editing. There is a GNOME coding style but many games pre-date this. Re-indenting the code interferes with revision tracking and fills patches with useless changes so please don't do it.
You will also want to look at the GNOME programming guidelines although these are a little old. 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.
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.
When you make a change please document it in the ChangeLog file. Using emacs the key-combination C-x 4 a will create a new entry ready for you to fill in. Not all GNOME modules use ChangeLog entries for minor changes but for Gnome Games we appreciate it. It helps explain your patch and ensures you get proper credit.
Between the time you started hacking and when you finish the code in SVN has probably changed. To re-synchronize your code use the command:
$ cvs -z3 -q -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome update -Pd gnome-gamesin the same directory you issues the previous cvs commands. You do not need to login again, in fact you only need to do that once ever. A list of files will be displayed along with a single character denoting their status. The only ones you need to know about are those labeled with a "C". The C stands for conflict and it means that someone has changed a file you changed and the changes are incompatible. If there is a C beside a file, edit that file to resolve the differences, SVN should have clearly marked the problem and there is usually no difficulty resolving them. ChangeLogs are a common source of conflicts.
Now that you have your code is synchronized with the GNOME SVN repository you need to generate a patch. You do this using the command:
$ cvs -z3 -q -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome diff -u gnome-games > patch-filepatch-file should now contain the difference between your code and the code in SVN. It is ready to be sent 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. If you generate a patch any other way, say using diff, then try and use the "unified" format. For diff use the -u switch.
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 SVN server so they can do it themselves.
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:
It is best that you do these things, but if you get confused the maintainer can help you.