Bug fix format requirements.

ASCII patch files are parsed for information to present to the user. The
following information is gleaned from the header of the patch file:

Author -- From a line that starts with "Author:", "author:", "Authors:",
"Author(s):", etc. Leading spaces are ignored. Only A is case-insensitive

Date -- From a line that starts with "Date:" or "date:". Leading spaces are
ignored. Only D is case-insensitive.

Programs Fixed -- From a line that starts with "Program:". Same flexibility as
is provided for Author above.

Files edited -- Parsed from the rest of the patch file, in lines that begin with
"+++ ", with no leading whitespace allowed and a space following 3 +s. These
MUST MUST MUST be relative to AMBERHOME even in individual patches. git does
this by default. See guidelines for creating bug fixes below.

Description -- parsed from line that starts with "Description:", same
flexibility as we have in Date, above. The description's end is determined
by a horizontal line of ------'s (and nothing else).

See the example header below:

********> bugfix 7
Author: Jason Swails
Date:  12 June 2011

Programs: readparm.py

Description: Add support for chamber-created prmtops to readparm.py, and
fix some LJ indexing issues (for extracting LJ parameters from A/BCOEFs)
---------------------------------------------------------------------------

The bottom line has nothing but ---'s (spaces are ignored), but has at least
one -. This signifies the end of the description (and header).

In the patch section itself, each edited file must be indicated via a path
relative to AMBERHOME and using the "+++ " and "--- " conventions. For example,

---------------------------------------------------------------------------
--- AmberTools/src/mmpbsa_py/MMPBSA_mods/alamdcrd.py
+++ AmberTools/src/mmpbsa_py/MMPBSA_mods/alamdcrd.py
@@ -371,7 +371,7 @@ class MutantMdcrd:
          coords_received = _scaledistance(coords_tosend, chdist)

          for i in range(3):
-            new_coords.append(coords_received[x+3])
+            new_coords.append(coords_received[i+3])

          coords_tosend = []
          coords_received = []

Patches require at least 3 lines of context on either side, and the format
shown above (this is done by default, again, by git).


PROCEDURE FOR GENERATING PATCHES:
---------------------------------

When in doubt, follow this procedure. Every release has associated with it a git
branch that we track that has bug fixes. At the time of writing, this is Amber11
and AmberTools 1.5, with branches amber11-with-patches and at15-with-patches.

The first way will be shown by using git diff on a tree BEFORE committing the
changes (I prefer this way, I think it is easiest!).

1) Generate patch BEFORE applying changes (I like this way better):

   a) If you need to cherry-pick a commit (or commits) over, use
         git cherry-pick -n <commit_id>

      Or, just make the changes to the tree without committing them

   b) Run git diff with the correct flags to get a properly-formatted patch
         git diff --no-prefix --patch-with-stat > bugfix.#

      # must be sequential in your bugfix repository!!!!

   c) Add a header to your bugfix according to the template above. The regular
      expressions are reasonably flexible, but don't put them to the test.

   d) Concatenate your bugfix to the end of the bugfix.all file for the users
      that DON'T want to use the new patching script.
         cat bugfix_file >> bugfix.all

   e) Email dac (or whoever is in charge of activating the website) to get the
      patch made active. patch_amber.py will automatically pick up
   
   f) Commit your change to the bug fix branch and push to the master
         git commit -a -m "commit message"

   g) Push your changes

2) Generate the patch after applying changes:

   Follow the same procedure as above, but for the git diff command run

git diff --no-prefix --patch-with-stat <last_commit> <bugfix_commit> > bugfix.#

Note that merges and cherry-picks may complicate this, so your best bet is to
use strategy 1.