Submitting Patches
==================

Repository Overview
===================

Vimprobable uses git [1], a distributed revision control system.  This
document is not intended to explain the git internals, for that there's
already a wealth of documentation on the Internet.

The main Vimprobable git repository [2] has two main branches:

master
vimprobable1

where master is for development on vimprobable2 and vimprobable1 is obviously
for vimprobable1 only.

When submitting a patch, the feature should be made on top of the master
branch, unless there is a good reason for knowing that the fix is wholly
applicable to vimprobable1.  In the general case though, most features are
submitted against master, and then manually ported to vimprobable1 where
applicable by the maintainer.  Not all features of Vimprobable2 are applicable
to Vimprobable1.

Preamble
========

If you've never used git before, git tracks meta-data about the committer
and the author, as part of a commit, hence:

$ git config [--global] user.name "Your name"
$ git config [--global] user.email "you@yourdomain.com"

Note that, if you already have this in the global ~/.gitconfig option, then
this will be used.  Setting this per-repository would involve not using the
"--global" flag above.   If you wish to use the same credentials always,
pass the "--global" option, as shown.

This is a one-off operation once the repository has been cloned, assuming
this information has ever been set before.

Coding style
============

Vimprobable uses four spaces by default, rather than literal hard tabs.
Most editors by default honour hard tabs only.  If you're using Vim (which
isn't an unreasonable assumption ;)) you can set the following:

:set expandtab ts=4 sts=4 sw=4

This should help reduce the number of whitespace fixups needed.

Use of topic branches
=====================

Git's use of branches makes it very easy to separate out different topics
from one another -- hence, for any feature or patch developed, they should
be done in their own topic branch, which is branched from the current HEAD
of origin/vimprobable.  Hence:

$ git checkout master
$ git pull
$ git checkout my-new-feature

Which at this point on means that you're on the "my-new-feature" branch, and
can then hack away.  When you've got a series of changes, it's best to
consider how to commit them.  Blindly doing:

$ git commit -a

which would commit all changes, won't make for a easy patch review, and will
likely just pollute the main git history with unnecessary noise.  Not to
mention, if a bug is discovered, finding it in amongst a huge code commit
like that would be rather annoying.  So instead, stage all the changes
you're doing logically together -- break up the feature into four or five
patches, or how ever many made sense.

For example, if you were writing a new feature, you might have:

* A patch to include any new header files.
* A patch for any new function prototypes.
* A patch per new function as it's written (or more, depending on the
  complexity).

This is nothing more than doing a:

$ git add foo.h
$ git commit

[Write commit message]

... do some more hacking.

$ git add main.c
$ git add utilities.c
$ git commit 

Working out what's changed
==========================

Once you're happy with the commits on the "my-new-feature" branch, you'll
obviously want to check that they still work on top of any new code that
might have been committed to the upstream branches since you creates the
"my-new-feature" branch.  This is important as you'll be basing your patches
against that.  Hence:

$ git checkout master
$ git pull
$ git checkout my-new-feature

(Note:  It's conceivable here that the "my-new-feature" branch might undergo
rebasing against origin/vimprobable2 -- although that's not being mentioned
here in the general case, but would equally be acceptable.)

Compiling/Testing patches
=========================

Before you send patches to the mailing list, please ensure that you compile
Vimprobable using the V_DEBUG target, as in the following:

$ make clean && make V_DEBUG=1

This not only compiles with "-g -ggdb" (for debug symbols), but also runs
some sanity check to ensure you've not missed anything.  If you have, fix up
any warnings or errors, and repeat the above command until it's clean.

Generating patches to send to the mailing list
==============================================

So, you've been working hard on your new feature, all your changes are sat
in a local topic branch; "my-new-feature", and you want to submit them to
the list.  You've already updated your copy of the vimprobable2 branch, and
your "my-new-feature" branch is checked-out, hence:

$ git format-patch -M -n --cover-letter -o patch_store master

Which will place a series of numbered commits in a directory called
"patch_store".  These can then be sent to the list [3] using the 
"git send-email" command.

Note that if this is more a bug-fix, or a single patch, it's not always
necessary to generate a cover-letter -- so that option to "git format-patch"
can be elided if necessary, but it doesn't really matter.

External hosting and pull-requests
==================================

Alternatively, if using a hosted Git service [4], then it's acceptable
that a pull-request can be issued on a branch against a repository.

References
==========

[1] http://git-scm.com
[2] https://sourceforge.net/p/vimprobable/code/
[3] vimprobable-users@lists.sourceforge.net
[4] http://repo.or.cz -- or -- http://github.com
