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