Getting the Source

As a patch author, you are most likely interested in the screened repository: darcs clone --lazy http://darcs.net/screened.

Updating, building and testing the code

To keep up with the latest patches, you can run the following command sequence in your local mirror of darcs’ repository:

cabal configure (only the first time)
cabal update
darcs pull
cabal build
cabal copy

To run darcs in a sandbox, the following commands produce a contained darcs repository:

darcs clone --lazy http://darcs.net/screened
cd screened
cabal sandbox init
cabal install --only-dependencies --enable-tests
cabal configure --enable-tests
cabal build (or cabal test)

We a small makefile for little helpers, right now, building tags:

make tags  ;# for vi
make TAGS  ;# for emacs, then use M-x visit-tags-file to load the TAGS file, then M-. to find identifiers in the code.

In general cabal test will run the tests.

To run a specific shell test, this might be useful:

dist/build/darcs-test/darcs-test -t testname

If you are using ‘cabal sandbox’ then the darcs-test exe may be in a slightly different folder under ./dist.

For performance-sensitive changes, some interesting targets are:

• cabal install --enable-library-profiling --enable-executable-profiling lets you have profile builds (along with the normal ones) at the cost of quadrupling compile time
• cabal install -frts is as fast as a regular compilation, and enables to do simple memory consumption measurings on the generated executable.

Preparing your patches

Conventions

• See CodingStyle for details.
• Patch names and long comment lines should be 72 characters or less.
• Did you resolve an issue? Prefix your patch name with resolve issueNNN: so that the bugtracker catch it
• Before spending a lot of time and effort on a new feature, please discuss your ideas with us either on IRC at #darcs on freenode.net, on the darcs-users mailing list or in the bug tracker.
• You can configure your computer to use darcs send --mail.
• In the body of your e-mail, please tell the following:
  • What your patch changes
  • Why your patch changes it
  • How you know your changes are correct
  • If you have future work in this line
• If you are sending a new version of a patch, use darcs send --mail --subject '[patchXXXX]' where XXXX is the patch number assigned by the patch tracker.

Prepare to be reviewed

All patches are reviewed by some other developers before being pushed to http://darcs.net/reviewed, so here is some advice.

• Friendly patch organisation

  • Please separate tidy-up and refactoring patches from patches that actually change functionality
  • If you want to make a big change in darcs, please avoid an all-or-nothing situation (where we either have to apply all of your patch bundle or none of it).

• Test cases

  • If your patch adds new functionality, we would like you to write RegressionTests for it.
  • Test should go in separate patches from the actual functionality (so that they can be accepted independently)
  • If your patch fixes issueXXXX, you should mv the corresponding test from failing-issueXXXX.sh to issueXXXX.sh.

• Documentation

  • New functions should have API-style documentation written in the Haddock syntax. Use cabal haddock to generates html reference documentation.
  • Please update the wiki after your patch has been accepted.

• darcs replace for superficial changes

  • Use darcs replace or try darcs record --look-for-replaces to create patches that commute better (fewer conflicts).
  • On the other hand, avoid using darcs replace to change the meaning of things (for example, to swap out one library with another one)
  • Do not use the tokens . and - in your darcs replace patches. The problem is that the . can affect code like lines.liftM

Sending your patches

Congratulations! You’ve written some lovely patches and now you want to get them into the mainline darcs.net. Here are some things you should know.

Darcs uses a patch tracker, which can be found at http://bugs.darcs.net/patch . When you use darcs send --mail, they will end up there automatically, waiting to be reviewed by another developer.

The typical flow of patches is:

1. created in your local repo
2. sent to the patch tracker (and copied to the darcs-devel mailing list)
3. pushed to screened
4. pushed to reviewed
5. pushed to the release branch.

Here are the three repositories that we use for Darcs development:

You should consider your patch as having been accepted once it makes it into reviewed. This happens once it has been reviewed and pushed to that repository.

Keep in mind that the developers love being nagged. So, if your patch is not getting much attention, ask on the darcs-devel list or IRC

Patch review

In Darcs’ developement, every contributed patch is supposed to be reviewed. This means the work you contribute should be presented in an understandable manner. Also this means one way to help Darcs development is to review other people’s work. The Core Team is responsible for pushing patches but everyone is welcome to do patch reviews.

Basic Process of Patch Submission and Acceptance

The basic rules are:

• all patches go to the patch tracker first
• all patches have to be reviewed
• you never push your own patches to the reviewed branch on darcs.net (this is for the people who have the privilege to do so)

Exceptions to these rules

• trivial patches (eg. typos in the comment) (if in doubt, it’s not obvious enough)
• patches about: contrib, distribution/packaging, build system, test cases
• the “hello, anybody? rule” : if a core team patch has not received review in a week, the submitter can push it directly to reviewed. Common-sense dictates that you avoid doing this if you think the patch really needs review.

Workflow

1. Somebody uploads a patch using http://bugs.darcs.net/patch?@template=item (sending patches via email to patches@darcs.net is unfortunately currently broken). The patch will have status needs-screening on the patch tracker. “Screening” simply consists of checking that the patch is sane in principle, with no attempt at thorough review, and pushing it to http://darcs.net/screened.
2. If the submitter is on the core team, they can screen their own patch. Patches from outside the core team should be screened by a core team member.
3. When a patch bundle has been screened, the patch tracker status should be set to needs-review.
4. Somebody should review the patch and push it to http://darcs.net/reviewed.
5. If you would like modifications to the bundle, say so and also set the status to “followup-requested”. If the bundles has already been screened, we no longer request patch amendments so much as follow up patches.
6. If you are happy with the patch bundle, you can push it to the reviewed branch at http://darcs.net/reviewed

Reviewing

First, you need to find patches to review.

• For this, go to the bugtracker, get an account and login. Then, look in the open patches section for unassigned patches which need review.
• Pick your favorite patch. If the rewiew is going to take you some time, assign it to yourself and set the status to review-in-progress.
• Do the review proper: test and read the patches; reply to the patch interleaving your comments with the body of the patch. Either reply via the patch-tracker’s web interface, or reply to the mailing list message. Your mail’s to: should be bugs@darcs.net, and the list will automatically get a copy of the message.
• If you think the patch should be applied, and you are not a Core Member, set the status to accepted-pending-tests (if you reply by mail, add [status=accepted-pending-tests] to the subject-line), and notify in the body that you have not applied yet. Please point out that you need a committer to push this patch.
• If you are a Core Member, set the status to accepted and push it.
• If you think the patch is inappropriate for darcs in a definitive way, set the status to rejected.
• If the patch should be changed before application, set the status to followup-requested.

Some tricks for saving time:

• get immediate feedback on IRC, but be sure to summarise and link the conversation afterwards
• if there are patches to amend, push the largest safe/acceptable subset of the bundle you can
• do not let trivial amendments block a patch; instead, as a reviewer, follow up by pushing corrections on your own

Core team: Pushing Patches

All people on the Core Team posses a “commit bit”: they have the permission to push patches to darcs.net. When a member is satisfied with a patch, they can push it. To push a patch, apply or pull it into your local mirror, and then darcs push darcs-unstable@darcs.net:screened (or to review, release).

Please also consult BuildBot after pushing changes, and possibly take steps necessary to get it back to green if anything breaks.

For help setting up your ssh keys, try this guide.

Links

• See Tips for a loose collection of tips
• Darcs Internals.
• Read Haskell
• api-doc with Haddock