PATCHES

   1 Submitting Patches
   2 ==================
   3
   4 Repository Overview
   5 ===================
   6
   7 Vimprobable uses git [1], a distributed revision control system.  This
   8 document is not intended to explain the git internals, for that there's
   9 already a wealth of documentation on the Internet.
  10
  11 The main Vimprobable git repository [2] has two main branches:
  12
  13 vimprobable1
  14 vimprobable2
  15
  16 which reflect the two supported versions of Vimprobable.
  17
  18 When submitting a patch, the feature should be made on top of the
  19 vimprobable2 branch, unless there is a good reason for knowing that the fix
  20 is wholly applicable to vimprobable1.  In the general case though, most
  21 features are submitted against vimprobable2, and then manually ported to
  22 vimprobable1 where applicable by the maintainer.  Not all features of
  23 Vimprobable2 are applicable to Vimprobable1.
  24
  25 Preamble
  26 ========
  27
  28 If you've never used git before, git tracks meta-data about the committer
  29 and the author, as part of a commit, hence:
  30
  31 $ git config [--global] user.name "Your name"
  32 $ git config [--global] user.email "you@yourdomain.com"
  33
  34 Note that, if you already have this in the global ~/.gitconfig option, then
  35 this will be used.  Setting this per-repository would involve not using the
  36 "--global" flag above.   If you wish to use the same credentials always,
  37 pass the "--global" option, as shown.
  38
  39 This is a one-off operation once the repository has been cloned, assuming
  40 this information has ever been set before.
  41
  42 Use of topic branches
  43 =====================
  44
  45 Git's use of branches makes it very easy to separate out different topics
  46 from one another -- hence, for any feature or patch developed, they should
  47 be done in their own topic branch, which is branched from the current HEAD
  48 of origin/vimprobable.  Hence:
  49
  50 $ git checkout vimprobable2
  51 $ git pull
  52 $ git checkout my-new-feature
  53
  54 Which at this point on means that you're on the "my-new-feature" branch, and
  55 can then hack away.  When you've got a series of changes, it's best to
  56 consider how to commit them.  Blindly doing:
  57
  58 $ git commit -a
  59
  60 which would commit all changes, won't make for a easy patch review, and will
  61 likely just pollute the main git history with unnecessary noise.  Not to
  62 mention, if a bug is discovered, finding it in amongst a huge code commit
  63 like that would be rather annoying.  So instead, stage all the changes
  64 you're doing logically together -- break up the feature into four or five
  65 patches, or how ever many made sense.
  66
  67 For example, if you were writing a new feature, you might have:
  68
  69 * A patch to include any new header files.
  70 * A patch for any new function prototypes.
  71 * A patch per new function as it's written (or more, depending on the
  72   complexity).
  73
  74 This is nothing more than doing a:
  75
  76 $ git add foo.h
  77 $ git commit
  78
  79 [Write commit message]
  80
  81 ... do some more hacking.
  82
  83 $ git add main.c
  84 $ git add utilities.c
  85 $ git commit
  86
  87 Working out what's changed
  88 ==========================
  89
  90 Once you're happy with the commits on the "my-new-feature" branch, you'll
  91 obviously want to check that they still work on top of any new code that
  92 might have been committed to the vimprobable* branches since you creates the
  93 "my-new-feature" branch.  This is important as you'll be basing your patches
  94 against that.  Hence:
  95
  96 $ git checkout vimprobable2
  97 $ git pull
  98 $ git checkout my-new-feature
  99
 100 (Note:  It's conceivable here that the "my-new-feature" branch might undergo
 101 rebasing against origin/vimprobable2 -- although that's not being mentioned
 102 here in the general case, but would equally be acceptable.)
 103
 104 Generating patches to send to the mailing list
 105 ==============================================
 106
 107 So, you've been working hard on your new feature, all your changes are sat
 108 in a local topic branch; "my-new-feature", and you want to submit them to
 109 the list.  You've already updated your copy of the vimprobable2 branch, and
 110 your "my-new-feature" branch is checked-out, hence:
 111
 112 $ git format-patch -M -n --cover-letter -o patch_store vimprobable2
 113
 114 Which will place a series of numbered commits in a directory called
 115 "patch_store".  These can then be sent to the list [3] using the
 116 "git send-email" command.
 117
 118 Note that if this is more a bug-fix, or a single patch, it's not always
 119 necessary to generate a cover-letter -- so that option to "git format-patch"
 120 can be elided if necessary, but it doesn't really matter.
 121
 122 External hosting and pull-requests
 123 ==================================
 124
 125 Alternatively, if using a hosted Git service [4], then it's acceptable
 126 that a pull-request can be issued on a branch against a repository.
 127
 128 References
 129 ==========
 130
 131 [1] http://git-scm.com
 132 [2] http://www.vimprobable.org/vimprobable.git
 133 [3] vimprobable-users@vimprobable.org
 134 [4] http://repo.or.cz -- or -- http://github.com