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.
Also, we're talking about Stonesoup here, but the principle could be applied to
any other program as well. :)
Required tools
--------------
At the very least you'll need the source code, and some helpful programs like
diff and grep. The latter come preinstalled with Unix, whereas Windows users
will have to download and install them. This may be a bit of work, but is
totally worth it if you're programming a lot. You can get them at e.g.
    http://gnuwin32.sourceforge.net/packages/diffutils.htm
    http://gnuwin32.sourceforge.net/packages/grep.htm
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.) Get the source code, either from the most recent release
    (http://sourceforge.net/projects/crawl-ref/files/) or use SVN to get the
    current trunk:
    svn co https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk/crawl-ref trunk
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.
3.) Once you've got everything set up, you should copy the folder containing
    the files you're going to change, i.e. docs/, dat/descript/ or the entire
    source/ folder, as appropriate. This is done so you can later easily create
    the patch against the original version.
4.) 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.
5.) Compile again to test your changes.
6.) Once everything works as it should, you can use diff or git to create a
    patch out of the differences between the two folders, e.g.
    diff -ur trunk-orig trunk-new > mypatch.diff
    You may want to apply the patch against the unmodified folder to test
    whether everything worked correctly.
7.) Upload the patch on the patch tracker of Sourceforge. 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 feature request, 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.5
    or r10078, and anything you think still may need to be improved or
    modified.
    Thank you! :D
Tips
----
Tip 1:  The code is rougly divided into files according to functionality that
        is reflected in the file names, so monstuff.cc, mon-util.cc and
        mstuff2.cc all handle code relating to monsters, while spl-data.h,
        spl-cast.cc and spells2.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 occurences 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
-------
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 enum.h (its
declaration), mon-spll.h (monsters "casting" the spell), spl-data.h (the
definition), and 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!

If the parameter list of a method runs longer than a line length (80 columns), 

If the parameter list of a method runs longer than a line length (80 columns),

  static void replace_area( int sx, int sy, int ex, int ey,
                            dungeon_feature_type replace,
                            dungeon_feature_type feature, unsigned mapmask)
  {
       [...]
  }

    static void replace_area(int sx, int sy, int ex, int ey,
                             dungeon_feature_type replace,
                             dungeon_feature_type feature, unsigned mapmask)
    {
        [...]
    }

        mons_place( MONS_GUARDIAN_NAGA, BEH_SLEEP, MHITNOT, true, 
                    sr.x1 + random2( sr.x2 - sr.x1 ), 

        mons_place( MONS_GUARDIAN_NAGA, BEH_SLEEP, MHITNOT, true,
                    sr.x1 + random2( sr.x2 - sr.x1 ),

Space allowing, logical connectives of different precedence should use nested 

Space allowing, logical connectives of different precedence should use nested

If a logical connective needs to be distributed over several lines, 
the conjunction/disjunction operators (&&, ||) should be placed at the 

If a logical connective needs to be distributed over several lines,
the conjunction/disjunction operators (&&, ||) should be placed at the

Since conjunctions (&&) take precedence over disjunctions (||), pure 
conjunctive logical connectives don't need to be bracketed, unless this is 

Since conjunctions (&&) take precedence over disjunctions (||), pure
conjunctive logical connectives don't need to be bracketed, unless this is

When naming variables, use underscores_as_spaces instead of mixedCase.  Other 

When naming variables, use underscores_as_spaces instead of mixedCase.  Other

Warning: This is a new convention, so much code doesn't follow it. 

Warning: This is a new convention, so much code doesn't follow it.

      int x, y;	

      int x, y;

If both the condition itself and the conditional code are single line 

If both the condition itself and the conditional code are single line

Also place braces if this is only the case because of one or more comment 

Also place braces if this is only the case because of one or more comment

   if (A)
   {
       if (B)
           do_something();
   }

    if (A)
    {
        if (B)
            do_something();
    }

   if (A && B)
       do_something();

    if (A && B)
        do_something();

Else, whenever if-conditional nesting can't be avoided, always use braces. I 

Else, whenever if-conditional nesting can't be avoided, always use braces. I

In a row of if-else if-statements or in a switch-case loop, the optional braces 
should be used if the bigger part of statements needs braces for logical 
reasons or because of one of the conventions above. Otherwise, they may be 

In a row of if-else if-statements or in a switch-case loop, the optional braces
should be used if the bigger part of statements needs braces for logical
reasons or because of one of the conventions above. Otherwise, they may be

When for-loops are nested and the outer loop has no further statements, the 

When for-loops are nested and the outer loop has no further statements, the

  for (int x = 0; x < GXM; x++)
      for (int y = 0; y < GYM; y++)
      {
          if (grd[x][y] == DNGN_LAVA)
              lava_spaces++;
          if (grd[x][y] == DNGN_DEEP_WATER || grd[x][y] == NGN_SHALLOW_WATER)
              water_spaces++;
      }

    for (int x = 0; x < GXM; x++)
        for (int y = 0; y < GYM; y++)
        {
            if (grd[x][y] == DNGN_LAVA)
                lava_spaces++;
            if (grd[x][y] == DNGN_DEEP_WATER || grd[x][y] == NGN_SHALLOW_WATER)
                water_spaces++;
        }

The same is true for combined for- and if-conditionals as long as all 

The same is true for combined for- and if-conditionals as long as all

If there are more than three nested statements with optional bracing, use braces 

If there are more than three nested statements with optional bracing, use braces

Should such nested code be followed by code other than a closing brace, 

Should such nested code be followed by code other than a closing brace,

If you feel that a method is complicated enough to be difficult to understand, 
or has restrictions or effects that might not be obvious, add explanatory 

If you feel that a method is complicated enough to be difficult to understand,
or has restrictions or effects that might not be obvious, add explanatory