HACKING

   1
   2 Conventions?  Are you kidding?  OK fine.
   3
   4 Code Branching Model
   5 ====================
   6
   7 The master branch is what we consider the main-line of development,
   8 and the last, non-rc tag on master is the most recent stable release.
   9
  10 Any branch with a "tmp/" prefix might be rebased (often), so keep that
  11 in mind when using or depending on one.
  12
  13 Any branch with a "tmp/review/" prefix corresponds to a patchset
  14 submitted to the mailing list.  We try to maintain these branches to
  15 make the review process easier for those not as familiar with patches
  16 via email.
  17
  18
  19 Current Trajectory
  20 ==================
  21
  22 Now that we've finished the 0.33 release, we're working on 0.34, and
  23 although we're not certain which new features will be included, we're
  24 considering:
  25
  26   - Migrating hashsplitting to C.
  27
  28   - Automatically splitting trees to avoid having to save large tree
  29     objects for large directories even if only a few files have
  30     changed or been added (e.g. maildirs).
  31
  32   - Moving all of the compoents of the index to sqlite.  Right now the
  33     main index is an mmapped file, and the hard link and metadata
  34     databases are pickled.  As a result the index isn't transactional
  35     and suffers from bugs caused by "skew" across the components.
  36
  37   - Better VFS performance for large repositories (i.e. fuse, ls,
  38     web...).
  39
  40   - Better VFS caching.
  41
  42   - Index improvements.
  43
  44   - Incremental indexing via inotify.
  45
  46   - Smarter (and quieter) handling of cross-filesystem metadata.
  47
  48   - Encryption.
  49
  50   - Support for alternate remote storage APIs.
  51
  52 If you have the time and inclination, please help review patches
  53 posted to the list, or post your own.  (See "ways to help" below.)
  54
  55
  56 More specific ways to help
  57 ==========================
  58
  59 Testing -- yes please.
  60
  61 With respect to patches, bup development is handled via the mailing
  62 list, and all patches should be sent to the list for review (see
  63 "Submitting Patches" below).
  64
  65 In most cases, we try to wait until we have at least one or two
  66 "Reviewed-by:" replies to a patch posted to the list before
  67 incorporating it into master, so reviews are an important way to help.
  68 We also love a good "Tested-by:" -- the more the merrier.
  69
  70
  71 Testing
  72 =======
  73
  74 Individual tests can be run via
  75
  76     ./pytest TEST
  77
  78 For example:
  79
  80     ./pytest test/int/test_git.py
  81     ./pytest test/ext/test-ftp
  82
  83 If you have the xdist module installed, then you can specify its `-n`
  84 option to run the tests in parallel (e.g. `./pytest -nauto ...`), or
  85 you can specify `-j` to make, which will be translated to xdist with
  86 `-j` becoming `-nauto` and `-jN` becoming `-nN`.
  87
  88 Internal tests that test bup's code directly are located in test/int,
  89 and external tests that test bup from the outside, typically by
  90 running the executable, are located in test/ext.
  91
  92 Currently, all pytests must be located in either test/ext or test/int.
  93 Internal test filenames must match test_*.py, and external tests must
  94 be located in text/ext and their filenames must match test-* (see
  95 test/ext/conftest.py for the handling of the latter).  Any paths
  96 matching those criteria will be automatically collected by pytest.
  97
  98 Some aspects of the environment are automatically restored after each
  99 test via fixtures in conftest.py, including the state of the
 100 environment variables and the working directory; the latter is reset
 101 to the top of the source tree.
 102
 103 Submitting patches
 104 ==================
 105
 106 As mentioned, all patches should be posted to the mailing list for
 107 review, and must be "signed off" by the author before official
 108 inclusion (see ./SIGNED-OFF-BY).  You can create a "signed off" set of
 109 patches in ./patches, ready for submission to the list, like this:
 110
 111     git format-patch -s -o patches origin/master
 112
 113 which will include all of the patches since origin/master on your
 114 current branch.  Then you can send them to the list like this:
 115
 116     git send-email --to bup-list@googlegroups.com --compose patches/*
 117
 118 The use of --compose will cause git to ask you to edit a cover letter
 119 that will be sent as the first message.
 120
 121 It's also possible to handle everything in one step:
 122
 123     git send-email -s --to bup-list@googlegroups.com --compose origin/master
 124
 125 and you can add --annotate if you'd like to review or edit each patch
 126 before it's sent.
 127
 128 For single patches, this might be easier:
 129
 130     git send-email -s --to bup-list@googlegroups.com --annotate -n1 HEAD
 131
 132 which will send the top patch on the current branch, and will stop to
 133 allow you to add comments.  You can add comments to the section with
 134 the diffstat without affecting the commit message.
 135
 136 Of course, unless your machine is set up to handle outgoing mail
 137 locally, you may need to configure git to be able to send mail.  See
 138 git-send-email(1) for further details.
 139
 140 Oh, and we do have a ./CODINGSTYLE, hobgoblins and all, though don't
 141 let that scare you off.  We're not all that fierce.
 142
 143
 144 Even More Generally
 145 ===================
 146
 147 It's not like we have a lot of hard and fast rules, but some of the
 148 ideas here aren't altogether terrible:
 149
 150   http://www.kernel.org/doc/Documentation/SubmittingPatches
 151
 152 In particular, we've been paying at least some attention to the bits
 153 regarding Acked-by:, Reported-by:, Tested-by: and Reviewed-by:.
 154
 155 <!--
 156 Local Variables:
 157 mode: markdown
 158 End:
 159 -->