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 Coding style
  43 ============
  44
  45 Vimprobable uses four spaces by default, rather than literal hard tabs.
  46 Most editors by default honour hard tabs only.  If you're using Vim (which
  47 isn't an unreasonable assumption ;)) you can set the following:
  48
  49 :set expandtab ts=4 sts=4 sw=4
  50
  51 This should help reduce the number of whitespace fixups needed.
  52
  53 Use of topic branches
  54 =====================
  55
  56 Git's use of branches makes it very easy to separate out different topics
  57 from one another -- hence, for any feature or patch developed, they should
  58 be done in their own topic branch, which is branched from the current HEAD
  59 of origin/vimprobable.  Hence:
  60
  61 $ git checkout vimprobable2
  62 $ git pull
  63 $ git checkout my-new-feature
  64
  65 Which at this point on means that you're on the "my-new-feature" branch, and
  66 can then hack away.  When you've got a series of changes, it's best to
  67 consider how to commit them.  Blindly doing:
  68
  69 $ git commit -a
  70
  71 which would commit all changes, won't make for a easy patch review, and will
  72 likely just pollute the main git history with unnecessary noise.  Not to
  73 mention, if a bug is discovered, finding it in amongst a huge code commit
  74 like that would be rather annoying.  So instead, stage all the changes
  75 you're doing logically together -- break up the feature into four or five
  76 patches, or how ever many made sense.
  77
  78 For example, if you were writing a new feature, you might have:
  79
  80 * A patch to include any new header files.
  81 * A patch for any new function prototypes.
  82 * A patch per new function as it's written (or more, depending on the
  83   complexity).
  84
  85 This is nothing more than doing a:
  86
  87 $ git add foo.h
  88 $ git commit
  89
  90 [Write commit message]
  91
  92 ... do some more hacking.
  93
  94 $ git add main.c
  95 $ git add utilities.c
  96 $ git commit
  97
  98 Working out what's changed
  99 ==========================
 100
 101 Once you're happy with the commits on the "my-new-feature" branch, you'll
 102 obviously want to check that they still work on top of any new code that
 103 might have been committed to the vimprobable* branches since you creates the
 104 "my-new-feature" branch.  This is important as you'll be basing your patches
 105 against that.  Hence:
 106
 107 $ git checkout vimprobable2
 108 $ git pull
 109 $ git checkout my-new-feature
 110
 111 (Note:  It's conceivable here that the "my-new-feature" branch might undergo
 112 rebasing against origin/vimprobable2 -- although that's not being mentioned
 113 here in the general case, but would equally be acceptable.)
 114
 115 Compiling/Testing patches
 116 =========================
 117
 118 Before you send patches to the mailing list, please ensure that you compile
 119 Vimprobable using the V_DEBUG target, as in the following:
 120
 121 $ make clean && make V_DEBUG=1
 122
 123 This not only compiles with "-g -ggdb" (for debug symbols), but also runs
 124 some sanity check to ensure you've not missed anything.  If you have, fix up
 125 any warnings or errors, and repeat the above command until it's clean.
 126
 127 Generating patches to send to the mailing list
 128 ==============================================
 129
 130 So, you've been working hard on your new feature, all your changes are sat
 131 in a local topic branch; "my-new-feature", and you want to submit them to
 132 the list.  You've already updated your copy of the vimprobable2 branch, and
 133 your "my-new-feature" branch is checked-out, hence:
 134
 135 $ git format-patch -M -n --cover-letter -o patch_store vimprobable2
 136
 137 Which will place a series of numbered commits in a directory called
 138 "patch_store".  These can then be sent to the list [3] using the
 139 "git send-email" command.
 140
 141 Note that if this is more a bug-fix, or a single patch, it's not always
 142 necessary to generate a cover-letter -- so that option to "git format-patch"
 143 can be elided if necessary, but it doesn't really matter.
 144
 145 External hosting and pull-requests
 146 ==================================
 147
 148 Alternatively, if using a hosted Git service [4], then it's acceptable
 149 that a pull-request can be issued on a branch against a repository.
 150
 151 References
 152 ==========
 153
 154 [1] http://git-scm.com
 155 [2] http://www.vimprobable.org/vimprobable.git
 156 [3] vimprobable-users@vimprobable.org
 157 [4] http://repo.or.cz -- or -- http://github.com