How to Write a Patch
====================
The following is a rough guide on how to write patches to the code. It is
meant to make writing patches easier to inexperienced programmers, but
following these steps does not guarantee that any patch will actually be
accepted - that depends entirely on content.
Required tools
--------------
The Stone Soup project uses git for version control. It is preferred, although
not mandatory, for the contributors to get acquinted with the git workflow and
submit their patches in the git format. For Windows, msysgit is a good,
self-contained package of all the required tools for Windows.
See develop/git/quickstart.txt for more information.
Main steps
----------
0.) If you're not interested in coding or have no intention of compiling the
game, you can still submit patches for the documentation, descriptions
or vaults. In that case, simply ignore the steps relating to compilation
and coding. You don't even need the source code for that, instead you can
simply use the binary distributation that also contains the relevant
text files.
1.) Make a local clone of the source code:
git clone https://github.com/crawl/crawl.git
2.) Compile the code. To do this you might have to install a compiler and/or
additional libraries. See INSTALL.txt for details. If you have any
questions, you can ask for help on crawl-ref-discuss@lists.sourceforge.net,
or in ##crawl-dev on irc.freenode.net.
3.) Now you can start tweaking the code. Depending on your coding background
you may want to experiment with smaller changes first. If you intend to
submit the patch to the dev team, please skim coding_conventions.txt.
Following these guidelines will save us some time later when integrating
the patch.
Remember that with git, you can work incrementally by making local commits.
You can even pull new changes from the development repository while you
work, by either making these incremental commits, or temporarily stashing
your changes, and then applying the stash after pulling.
4.) Compile again to test your changes.
5.) Once everything works as it should, run util/checkwhite to fix a few
formatting problems. Now, you should make a local commit (or several), and
use git format-patch to produce easily appliable patches:
git format-patch -n
Where n is the number of commits you made. Each is made into a separate
patch file.
6.) Upload the patch file(s) on Mantis at
http://crawl.develz.org/mantis/main_page.php
Here it is immensely helpful if you give a summary of what the patch is
about. If you created it in response to a bug report or an "Implementable",
mention the id, and you might also want to post a reply in said item
pointing out your new patch. Please also mention the revision/version you
used for patching, e.g. 0.6 or 1d611744b (the first 7 or 8 characters
should suffice), and anything you think may still need to be improved or
modified.
Thank you! :D
Tips
----
Tip 1: The code is roughly divided into files according to functionality that
is reflected in the file names, so mon-gear.cc, mon-stuff.cc
and mon-util.cc all handle code relating to monsters, while spl-data.h,
spl-cast.cc and spl-summoning.cc deal with spells. Note that related
code can still be found in other files, too, but these are a good
starting point.
Tip 2: Start out with the simple, generic stuff where you only have to copy
and minimally tweak existing code, and only once that works move on to
the more complicated implementations.
Tip 3: Use grep to find all occurrences of a similar instance of the same type
as the one you're implementing, e.g.
grep GOD_ELYVILON *.cc when adding a new god, or
grep SCR_FOG *.cc when adding a new scroll.
That way you'll be able to repurpose a lot of code for your new
implementation, and it also helps cut down on coding errors.
Example
-------
In the following, file names and code distribution refer to Stone Soup 0.5,
and may very well have changed in the meantime. Still, the mechanics of finding
and copying code from similar concepts are unchanged.
I want to add a spell that creates some kind of clouds. The first similar spell
I can think of is Mephitic Cloud. I know that this spell is defined as
SPELL_MEPHITIC_CLOUD (and if I didn't know I could find out by grepping for
"Mephitic Cloud"), so I type (within the source folder)
grep SPELL_MEPHITIC_CLOUD *.h and
grep SPELL_MEPHITIC_CLOUD *.cc
... which tells me that code regarding this spell turns up in the following
header files:
* enum.h (its declaration)
* mon-spll.h (monsters "casting" the spell)
* spl-data.h (the definition)
... as well as in ghost.cc (monster spell), it_use3.cc (some kind of misc.
item, maybe), mstuff2.cc (helpfully with a comment mentioning swamp drakes),
spl-book.cc (spellbooks that contain this spell), and spl-cast.cc (actually
casting the spell).
That gives me some ideas on where to start looking at code to duplicate
for my new spell. I'd start out with the basics, the declaration and
definition, copying all values from Mephitic Cloud and only changing the
SPELL_xxxx tag. Then I add the new spell to the list in spl-cast.cc, at which
point I'll also notice that Mephitic Cloud uses a function called
stinking_cloud() and that various other cloud spells (helpfully sorted by
effect type) use functions like cast_big_c() and others. Using grep I can
quickly find out that both functions are declared in spells1.h, meaning their
definitions can be found in spells1.cc.
stinking_cloud() contains a definition of a beam that defines damage and
such. The various properties are not self-explanatory but they're also not
totally obscure, so you should be able to find out a lot about them by just
fiddling with the values. In particular, beam.flavour is set to something
called BEAM_POTION_STINKING_CLOUD which looks interesting enough to check
out, so I grep the source (*.h and *.cc) for all occurences and have a look
at all files this turns up. And so on.
Evaluating and prioritising the findings takes some experience with the source
code but even if you have no idea what the files are likely to contain, using
grep still greatly reduces the number of files you have to look at. To find
the code you're interested in, search the files for the same keyword you used
for grepping.
Good luck with your patch! If you have any questions, don't hesitate to ask.
Thank you for your support!
