Guidelines for patch submissions
================================



What is a patch?
----------------

A patch file, also known as a "diff", is a textual representation of
changes to source code. Patches are readable enough to be reviewed by
humans and at the same time regular enough to be processed by
programs. The `patch' utility is used to change the source code in
the manner that the patch describes, this being called "applying" the
patch. Patches work even on files that have been modified
independently of the modifications in the patch, as long as those
other changes do not conflict with the patch.

Because of these properties, patches are the preferred means of
distributing the changes to a free software project. If you have made
a change to ABINIT and would like to contribute it, you will need to
create a patch and send it to the developers; please read on.



Where to send the patches
-------------------------

Patches intended to be applied to ABINIT should be mailed to
<bugs@abinit.org>. Each patch will be reviewed by the developers,
and will be acked and added to the distribution, or rejected with
an explanation. Unfortunately, the developers are often busy with
their day jobs, so the review process can take a while.

If you want to discuss your patch with the community of ABINIT users and
developers, it is OK to send it to the developers' list at
<developers@abinit.org>. If the patch is really huge (more than 100K
or so), you may want to put it on the web and post the URL.

EVERY patch should be accompanied by an explanation of what the patch
changes, and why the change is desirable or necessary. The
explanation need not be long, but please don't just send a patch
without any accompanying text.

Normally, a patch can be just inserted into the message, after the
explanation and the ChangeLog entry. However, if your mail composer
or gateway is inclined to munge patches, e.g. by wrapping long lines,
please send them out as a MIME attachment. It is important that the
patch survives the travel unchanged so that we can feed it to the
`patch' utility after reviewing it.



How to create patches
---------------------

First, please make sure that you are working with the latest version
of the source -- changing obsolete code is a waste of time. Working
on the latest release is acceptable in most cases, but it is better
yet to download the very latest sources from the publicly-available
Bazaar branches and work on those. The BZR pages in the developer's
corner at <http://dev.abinit.org/environment> explain what Bazaar
is and how to check out ABINIT's source code from the public
repository.

Patches are created using the `diff' program. When making patches,
please use the `-u' option, or if your diff doesn't support it, `-c'.
Ordinary (context-free) diffs are notoriously prone to errors, since
line numbers tend to change when others make changes to the same
source file.

In the general case, `diff' is used like this:

    diff -u ORIGFILE CHANGEDFILE > patch.txt

Also, it is helpful if you create the patch in the top level of
the ABINIT source directory. For example:

    cp src/03iovars/indefo.F90 src/03iovars/indefo.F90.orig
    ... modify src/03iovars/indefo.F90 ...
    diff -u src/03iovars/indefo.F90.orig src/03iovars/indefo.F90 > patch.txt

If your patch changes more than one file, feel free to simply
concatenate the diffs of different files into a large diff:

    (diff -u foo.orig foo; diff -u bar.orig bar) > patch.txt

The alternative is to leave the unchanged source lying around and use
the `-r' option to compare entire directories:

    diff -ur abinit-5.5.3.orig abinit-5.5.3 > patch.txt

If you do that, please be careful not to include the differences to
automatically generated files.

If you run on Windows and don't have `diff' handy, please get one.
It's extremely hard to review changes to files unless they're in the
form of a patch. If you really cannot use a variant of `diff', then
mail us the whole new file and specify which version of ABINIT you
changed; that way we will be able to generate the diff ourselves.

Finally, if your changes introduce new files, or if they change the
old files past all recognition (e.g. by completely reimplementing the
old stuff), sending a patch obviously doesn't make sense. In that
case, just attach the files along with an explanation of what is being
changed. Another way is to use the `-N' option of diff if you
generate the patch by recursively comparing the directories (`diff -r').



Standards and coding style
--------------------------

Everywhere it is possible, ABINIT abides by the GNU coding standards,
available at:

    http://www.gnu.org/prep/standards.html

I consider perhaps the most important single point in that entire
document to be the "no arbitrary limits" rule. Even where ABINIT's
coding is less than exemplary, it respects that rule. There should be
no exceptions.

Here is a short recap of the GNU formatting and naming conventions,
partly borrowed from XEmacs:

  * Put a space after every comma.

  * Put a space before the parenthesis that begins a function call,
    macro call, function declaration or definition, or control
    statement (if, while, switch, for). (DO NOT do this for macro
    definitions; this is invalid preprocessor syntax.)

  * Variable and function names should be all lowercase, with
    underscores separating words, except for a prefixing tag, which may
    be in uppercase. Do not use the mixed-case convention (e.g.
    SetVariableToValue ()) and *especially* do not use Microsoft
    Hungarian notation (char **rgszRedundantTag).

  * Preprocessor constants and enumerations should be all uppercase,
    and should be prefixed with a tag that groups related constants
    together.



ChangeLog policy
----------------

Each patch should be accompanied by an update to the appropriate
ChangeLog file. Please don't mail diffs of ChangeLog files because
they have an extremely high rate of failure; just mail us the new
entries you added to the ChangeLog. Patches without a ChangeLog entry
will be accepted, but this creates additional work for the
maintainers, so please do take the time to write one.

Guidelines for writing ChangeLog entries are also governed by the GNU
coding standards, under the "Change Logs" section.



Acknowledgments
---------------

This document has been written using part og GNU Wget's documentation
as a starting point. We gratefully thank Wget's contributors.

