147 lines
5.0 KiB
Plaintext
147 lines
5.0 KiB
Plaintext
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:
|
|
|
|
vimprobable1
|
|
vimprobable2
|
|
|
|
which reflect the two supported versions of Vimprobable.
|
|
|
|
When submitting a patch, the feature should be made on top of the
|
|
vimprobable2 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 vimprobable2, 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.
|
|
|
|
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 vimprobable2
|
|
$ 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 vimprobable* branches since you creates the
|
|
"my-new-feature" branch. This is important as you'll be basing your patches
|
|
against that. Hence:
|
|
|
|
$ git checkout vimprobable2
|
|
$ 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 vimprobable2
|
|
|
|
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] http://www.vimprobable.org/vimprobable.git
|
|
[3] vimprobable-users@vimprobable.org
|
|
[4] http://repo.or.cz -- or -- http://github.com
|