* This file This file attempts to give some hints to people whishing to contribute to Heroes. Questions or suggestions about this file can be sent to . * Developer tools used in Heroes Required to bootstrap a CVS checkout: autoconf 2.50 (from ftp.gnu.org) automake 1.4d (from sources.redhat.com/automake) autogen 5.2 (from autogen.sourceforge.net) gettext 0.10.38 (from alpha.gnu.org) gperf (from ftp.gnu.org) gnu make (from ftp.gnu.org) (numbers are *minimal* versions required) Optionally needed if you change some specific parts of the game: help2man (http://www.gnu.org/software/help2man/) texinfo (from ftp.gnu.org) zip (ftp://ftp.cdrom.com/pub/infozip/src/zip23.tar.gz) unzip (ftp://ftp.cdrom.com/pub/infozip/src/unzip540.tar.gz) Required to commit a patch if you have write access to the CVS server: cvs-utils (from subversions.gnu.org) * Translating message catalogs Heroes use gettext as internationalization library, and gettext come with a manual which is really worth reading. Translating Heroes' messages is not as straightforward as translating a console-based utility would be. In short, there are two kind of messages: those printed on the console (--help output, error messages,...), and those drawn during the game (menu entries, online help,...). The former cause no particular problem. The latter use home-made fonts (coming with the heroes-data package) and those fonts do not always implement the full Latin-1 character set. You ought to configure Heroes with --enable-debug. When configured like this, Heroes will check most messages at startup and report those who contains non-drawable characters. If you have done a new translation, want to try it, but don't want to install all the above tools (autoconf, automake, etc.), do the following: open the file `configure' in your favorite editor, locate the line starting with `ALL_LINGUAS=' and add your language here, then rerun configure and reinstall the game, your catalog should be installed with the others. Note that you will still need gettext installed. (For people who have the latest autoconf and automake, the correct way to add a new catalog is to edit the same line in configure.ac, of course). * Sending patches If you patched Heroes and want to have your patch included in a next release, please send it to . (This is a general discussion list, there is presently no list dedicated to patches.) * General coding conventions We try to follow the GNU standards (with some slight modifications as it will be noted below) and most of their guidelines are not repeated here. standards.info (available on every good GNU system) is a recommended reading. ** Formatting Look the code around to see how the code is formated. Basically this is the GNU formatting standard, except that braces are kept on the same line as the flow-control keywords, as in do { if (cond2) { /* ... */ } else if (cond3) { /* ... */ } else { /* ... */ } } while (cond1); The corresponding indent options are `-br' and `-ce'. ** Typenames Typenames used in Heroes code used to be suffixed by `_t'. Unfortunatelly, all such typenames (ending with `_t') are reserved by POSIX, and OS vendors usually add new types using this convention. Therefore using the same naming was not a really great idea: name clashes occured twice (`timer_t' happened to be already defined on NetBSD, `level_t' was defined on OSF) before I decide to use another convention. Typenames in Heroes now starts with a_ or an_ (e.g. `a_level', `an_option'). This idea came from http://gcc.gnu.org/ml/gcc/2001-06/msg01006.html. ** Includes Any .c-file should include "system.h" as the first included file. Read the beginning of system.h for more explanations. Any .h-file can assume system.h has already been included, but should include other local headers needed (e.g. type declaration used in function prototypes) so that inclusion order is not important. ** FIXME The keywords `FIXME:', `NOTE:', and `WARNING:' can be used to emphasis any comment in the sources. Try to make the important part of your comment fit on the same line of the keyword, such that `grep FIXME: *.[ch]' give a nice summary. ** ChangeLog Any change to a file that goes into the distribution should have a corresponding ChangeLog entry (verbosity is prefered). Removals in files BUGS and TODO or additions to THANKS can be implicit (i.e. without ChangeLog entries). ** RCS keywords Do not use them; they make mixing of files from different projects complicated. If you stole a file from another project which has such keywords, don't remove them, just "cvs add -ko" the file (-ko prevent future keywords substitution). Actually just "cvs add -ko" any file. * Files that should not be changed Some files are auto-generated, or maintained elsewhere and should therefore not be modified directly. ** Auto-generated files Files which will go into the distribution, but are not in the CVS because they can be generated from files already kept the CVS. aclocal.m4 (generated by aclocal from configure.ac and m4/*) configure (generated by autoconf from configure.ac) THANKS (generated by Makefile or GNUmakefile using autogen from src/people.{def,tpl}) THANKS (generated by Makefile or GNUmakefile using autogen from src/people.{def,tpl}) src/config.h.in (generated by autoheader from configure.ac and aclocal.m4) **/Makefile.in (generated by automake from configure.ac) arch/VisualC/VisualC.zip (generated by arch/Makefile using zip from arch/Visual/*) src/rsc_files_hash.c (generated by src/Makefile using gperf from src/rsc_files.gperf) src/debugchn.h (generated by src/Makefile using AutoGen from src/debugchn.{def,tpl}) src/debughash.gperf (generated by src/Makefile using AutoGen from src/debugchn.{def,tpl}) src/debughash.c (generated by src/Makefile using gperf from src/debughash.gperf) src/prefs.c (generated by src/Makefile using AutoGen from src/prefs.{def,tpl}) src/prefs.h (generated by src/Makefile using AutoGen from src/prefs.{def,tpl}) src/people.c (generated by src/Makefile using autogen from src/people.{def,tpl}) doc/heroes.info (generated by doc/Makefile using makeinfo from src/heroes.texi) doc/debugchn.info (generated by doc/Makefile using AutoGen from src/debugchn.{def,tpl}) man/heroes.6 (generated by man/Makefile using help2man from the Heroes binary) doc/people.texi (generated by doc/Makefile using autogen from src/people.{def,tpl}) po/POTFILES.in (generated by tools/genpotfiles.sh) m4/Makefile.inc (generated by tools/genm4mam.sh) ** Not generated, but added automatically by automake or gettextize ... and therefore not in CVS. automake adds these COPYING, INSTALL, tools/config.guess, tools/config.sub, tools/depcomp, tools/install-sh, tools/mdate-sh, tools/missing, tools/mkinstalldirs, tools/texinfo.tex gettextize adds all the files in intl/, as well as po/Makefile.in.in and ABOUT-NLS. ** Files in CVS, but maintained elsewhere Avoid any change to these files, if possible. (And report any change upstream, of course.) lib/alloca.c (from fetish) lib/basename.c (from fetish) lib/dirname.c (from fetish) lib/dirname.h (from fetish) lib/ftruncate.c (from fetish) lib/getopt.c (from glibc) lib/getopt1.c (from glibc) lib/gnugetopt.h (from glibc, where it is named getopt.h) lib/error.c (from glibc) lib/error.h (from glibc) lib/hash.c (from fetish) lib/hash.h (from fetish) lib/isdir.c (from fetish) lib/malloc.c (from fetish) lib/realloc.h (from fetish) lib/realloc.h (from fetish) lib/stpcpy.c (from fetish) lib/strcasecmp.c (from fetish) lib/stripslash.c (from fetish) lib/strndup.c (from glibc) lib/xalloc.c (from fetish) lib/xmalloc.c (from fetish) lib/xstrdup.c (from fetish) m4/dos.m4 (from fetish) m4/ftruncate.m4 (from fetish) m4/glibc21.m4 (from fetish) m4/gnu-source.m4 (from fetish) m4/malloc.m4 (from fetish) m4/realloc.m4 (from fetish) m4/strerror_r.m4 (from fetish) po/Makefile.in.in (from fetish) Jim Meyering is keeping all the above files up to date in his fetish tools (fileutils, textutils, or shellutils). The script tools/fetish-sync.sh can be used to upgrade all of them from the latest fetish release. m4/codeset.m4 (from gettext) m4/gettext.m4 (from gettext) m4/iconv.m4 (from gettext) m4/isc-posix.m4 (from gettext) m4/lcmessage.m4 (from gettext) m4/progtest.m4 (from gettext) These latter files come from the gettext package. Other files: lib/fstrcmp.c (from gettext, via libit) lib/fstrcmp.h (from gettext, via libit) lib/getshline.c (from a2ps) lib/getshline.h (from a2ps) lib/w_dirent.c (from mingw, originally dirent.c) lib/w_dirent.h (from mingw, originally dirent.h) ** Autogenerated, kept in CVS README: generated by the root Makefile from the Texinfo manual (when you run `make README' or `make dist'). It needs to be kept in CVS because it is checked out by the webpages' Makefile. * CVS ** Building from CVS As generated files are not all kept in CVS, you need to generate them after your first checkout. This is done by running GNU make. The first time you run make on your CVS checkout it will generate the file THANKS and AUTHORS, and then call the script tools/cvsboot.sh which will take care of generating the other missing file. After you have run cvsboot, you will be able to make a first build first build (./configure; make) to create the documentation and the other files generated by Makefile rules. cvsboot calls a few other commands you may want to use separately: tools/upgettext.sh: populate intl/, and install some other gettext files tools/autogen.sh: build autotools files (configure, */makefile.in, etc.) tools/genm4mam.sh: build m4/Makefile.am tools/genpotfiles.sh: build po/POTFILES.in All these commands shoud be run from the top level directory. ** Committing changes If you have write access to the CVS, you shall use clcommit to commit your patches (clcommit can be obtained from the cvs-tools modules of subversion.gnu.org CVS server). clcommit will use your ChangeLog entry as a commit message, and complain if you forgot to make a ChangeLog entry. ** Tracking other changes CVS commit are automatically sent as patches, to heroes-commits@lists.sourceforge.net. You can subscribe to this list using the following page. http://lists.sourceforge.net/mailman/listinfo/heroes-commits ** Committing patches from other people If there is no ChangeLog entry, write one (and add a "From " comment line) or ask the author to make one. Don't forget to put the author in THANKS. ** Bug fixes If you fix a bug reported by someone, add a "Reported by " line to your ChangeLog entry. Put him in THANKS too. ** Tag and branches The main trunk should remain the latest, bleeding edge, development version of the game. Releases are tagged using symbolic name such as heroes_0_5 (for heroes-0.5) or heroes_0_6b (for heroes-0.6b). After a public release there is usually an errata branch (e.g. heroes_0_6_errata) created, and rooted on the corresponding release version. This branch is for important bug fixes (e.g. bugs that prevent the game to compile or run). Every patch commited to that branch should be merged in the main trunk. * Design guidelines ** Console output There is four kinds of console messages in Heroes. a) warning messages, i.e., non fatal errors; output with wmsg() b) error messages, for fatal errors; output with emsg() c) debug messages, i.e. traces selected with the `-v' switches; output with dmsg(). d) standard messages; output with printf(), puts() or whatever. Groups a) and b) are printed to stderr because they are errors, while groups c) and d) are printed to stdin because they are answers to user requests (e.g. the output of --help goes to stdout because the user asked for it). As far i18n is concerned, the idea is to internationalize only what is worth to the user, and keep in english all messages destined to the developper. Therefore groups a), b), and d) are translated, while group c) is not. * Release process ** Before a public release - Update externally-maintained files - Update administrative files: + src/people.def (add new contributions if not already done) + NEWS, TODO, BUGS must be up to date - Set version number in configure.ac - run tools/cvsboot.sh and make a dummy build (to update the generated file to the new version) - build the distribution using `make distcheck' in addition to making a distribution, this will actually perform five builds of the game using differents configurations (so you need all supported libraries installed to do that) If the above was successful: - commit the changes to CVS - tag the repository (cvs tag heroes_xx_yy) - update the webpages (the repository needs to be tagged before) ** Where to upload SourceForge ftp://upload.sourceforge.net/incoming/ https://sourceforge.net/project/admin/editpackages.php?group_id=7982 MetaLab ftp://metalab.unc.edu/incoming/Linux/ ** Where to announce - mail: heroes-announce@lists.sourceforge.net games-announce@lists.sourceforge.net news@linuxgames.com (http://www.linuxgames.com/) sdl-announce@lokigames.com - news: comp.os.linux.applications (moderated) - web: http://freshmeat.net/projects/heroes/ http://www.linuxapps.com/?page=update&id=3154 http://happypenguin.org/show?Heroes https://sourceforge.net/news/submit.php?group_id=7982 Local Variables: mode: outline End: