This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

1. 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.

Contents

  1. Gnome Games - Developer's Guidelines
    1. I've got this great idea !
    2. I want to help, any suggestions ?
    3. Getting the code
    4. Required library dependencies
    5. Finding your way around
    6. Style
    7. Internationalization
    8. Sending Your Changes Upstream
    9. Translating Documents
      1. What you must do
      2. What you should do
      3. Suggestions

1.1. 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.

1.2. 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.

1.3. 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.

1.4. Required library dependencies

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

These packages are optional, but highly recommended:

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.

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:

1.5. 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.

1.6. 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.

1.7. 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.

1.8. 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.

1.9. 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:

1.9.1. What you must do

1.9.2. What you should do

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

1.9.3. Suggestions

2024-10-23 10:58