X-Git-Url: https://arthur.barton.de/gitweb/?a=blobdiff_plain;f=HACKING;h=9d2f4ff506e5716993edd41b248935bbc9147283;hb=36b36f2d55af5c8a7c69f9a3ba74a978d2f89e1a;hp=f79041d98f18b6ba73ab0adbd2976e8421b6fe1f;hpb=a996c1fc377c567830db8f139ac9fadb0f144e84;p=bup.git diff --git a/HACKING b/HACKING index f79041d..9d2f4ff 100644 --- a/HACKING +++ b/HACKING @@ -7,24 +7,39 @@ Code Branching Model The master branch is what we consider the main-line of development, and the last, non-rc tag on master is the most recent stable release. -Of course, in all fairness, it has been a *long* time since the last -stable release, but we're working fairly hard to fix that -- no, -seriously. - Any branch with a "tmp/" prefix might be rebased (often), so keep that in mind when using or depending on one. +Any branch with a "tmp/review/" prefix corresponds to a patchset +submitted to the mailing list. We try to maintain these branches to +make the review process easier for those not as familiar with patches +via email. + Current Trajectory ================== -At the moment, one of the primary goals is to add support for -filesystem metadata. That work is being handled via tmp/pending/meta, -and we're in the process of trying to vet those patches for master. -Once that's been done, we're planning to produce a new stable release. +Now that we've finished the 0.31 release, we're working on 0.32, and +although we're not certain which new features will be included, we're +considering: + + - Better VFS performance for large repositories (i.e. fuse, ls, + web...). + + - Better VFS caching. + + - Index improvements. -If you have the time and inclination, please help review those patches -as they're posted to the list. (See below.) + - Incremental indexing via inotify. + + - Smarter (and quieter) handling of cross-filesystem metadata. + + - Encryption. + + - Support for alternate remote storage APIs. + +If you have the time and inclination, please help review patches +posted to the list, or post your own. (See "ways to help" below.) More specific ways to help @@ -36,34 +51,65 @@ With respect to patches, bup development is handled via the mailing list, and all patches should be sent to the list for review (see "Submitting Patches" below). -In most cases, we try to wait until we have at least two +In most cases, we try to wait until we have at least one or two "Reviewed-by:" replies to a patch posted to the list before incorporating it into master, so reviews are an important way to help. We also love a good "Tested-by:" -- the more the merrier. +Testing +======= + +Individual tests can be run via + + ./pytest TEST + +For example: + + ./pytest test/int/test_git.py + ./pytest test/ext/test-ftp + +If you have the xdist module installed, then you can specify its `-n` +option to run the tests in parallel (e.g. `./pytest -nauto ...`), or +you can specify `-j` to make, which will be translated to xdist with +`-j` becoming `-nauto` and `-jN` becoming `-nN`. + +Internal tests that test bup's code directly are located in test/int, +and external tests that test bup from the outside, typically by +running the executable, are located in test/ext. + +Currently, all pytests must be located in either test/ext or test/int. +Internal test filenames must match test_*.py, and external tests must +be located in text/ext and their filenames must match test-* (see +test/ext/conftest.py for the handling of the latter). Any paths +matching those criteria will be automatically collected by pytest. + +Some aspects of the environment are automatically restored after each +test via fixtures in conftest.py, including the state of the +environment variables and the working directory; the latter is reset +to the top of the source tree. + Submitting patches ================== As mentioned, all patches should be posted to the mailing list for -review. - -You can create a "signed off" (see ./SIGNED-OFF-BY) set of patches in -./pending, ready for submission to the list, like this: +review, and must be "signed off" by the author before official +inclusion (see ./SIGNED-OFF-BY). You can create a "signed off" set of +patches in ./patches, ready for submission to the list, like this: - git format-patch -s -o pending origin/master + git format-patch -s -o patches origin/master which will include all of the patches since origin/master on your current branch. Then you can send them to the list like this: - git send-email --to bup-list@googlegroups.com --compose patches/* + git send-email --to bup-list@googlegroups.com --compose patches/* The use of --compose will cause git to ask you to edit a cover letter that will be sent as the first message. It's also possible to handle everything in one step: - git send-email -s --to bup-list@googlegroups.com --compose origin/master + git send-email -s --to bup-list@googlegroups.com --compose origin/master and you can add --annotate if you'd like to review or edit each patch before it's sent. @@ -80,7 +126,7 @@ Of course, unless your machine is set up to handle outgoing mail locally, you may need to configure git to be able to send mail. See git-send-email(1) for further details. -Oh, and we do have a ./CODING-STYLE, hobgoblins and all, though don't +Oh, and we do have a ./CODINGSTYLE, hobgoblins and all, though don't let that scare you off. We're not all that fierce.