Keeping Up With the Latest Patches

The following command sequence updates your local environment with darcs' latest development version.

cabal update
darcs pull -a
cabal build
cabal test
cabal install

The impatient may prefer:

cabal update && darcs pull -a && cabal install

Conventions

• Coding

  • See CodingStyle for details

• Patches

  • Keep your patch names down to 72 characters or less. This isn't a hard and fast rule, and most of us have broken it on more than one occasion, but it does make life a tiny bit easier for everybody if you follow it.
  • Likewise, if you supply a long comment to your patch, please use a line length of 72 characters or less in your comment.
  • Did you resolve an issue? Prefix your patch name with 'resolve issueNNN:' This will be picked up automatically by our bugtracker integration
  • Send your patches to http://darcs.net. This is the repository we expect most developers to be working from.

• Collaboration

  • 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.

• Communication

  • Check to make sure your computer is correctly configured to use Darcs send first. For more details, see the guide for sending patches to the darcs team.

  • Send with --edit-description and please tell the following as it will greatly increase the success of your contributions and collaborations with us:

    • 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 amending a patch, it's usually helpful to use the darcs send --subject '[patchXX]' where XX is the patch number assigned by the patch tracker.

Things we like

• Friendly patch organisation

  • Please separate your tidy-up and refactoring patches from patches that actually change functionality
  • Test cases should go in separate patches from the actual functionality (so that they can be accepted independently of the actual code)
  • Open question: should documentation patches be independent from code patches?

• Gradual and standalone changes

  • If you want to make a big change in darcs, please try and avoid an all-or-nothing situation (where we either have to apply all of your patch bundle or none of it). Note that this isn't so much a question of patch size, but of the logical organisation behind your patches. We like partial credit.

• Watching out for future pitfalls

  • Sometimes our reviewers will request modifications to a patch, not because there is any bugs in the patch itself, but because we think the patch will lead to future bugs if people make obvious next-step modifications to the code. So please be patient with us if we challenge your patch on these grounds and stick around so that we can keep making darcs better :-)

• Test cases

  • If your patch adds new functionality, we would like you to write some test cases for it. Please see the tests directory for functional tests, or src/unit.lhs for unit tests.
  • If your patch resolves an issue, you should also mv the corresponding functional test from the bugs directory to the tests directory
  • See RegressionTests to ensure that your tests will work on all platforms supported by darcs

• Documentation

  • New functions should have API-style documentation written in the Haddock syntax. At the time of this writing (2008-10), darcs is not yet fully haddocked, although we are working on it!
  • Please update the user manual at the same time as you are making your patch

• Darcs Replace for superficial changes

  • If your changes can be expressed by a search and replace, please use 'darcs replace' as it is much easier to review and the resulting patches will commute better (fewer conflicts).
  • On the other hand, avoid using darcs replace to change the meaning of things as this will lead to confusion. For example, don't use darcs replace to swap out one library with another one; actually change the hunks. On the other hand, do use darcs replace underscore_names with camelCase names.
  • Try to avoid using the tokens . and - in your darcs replace patches that affect Haskell files. The problem is that the . can affect code like lines.liftM

• Portable Code

  • We like to keep darcs building on multiple platforms and several versions of GHC. As of 2009-09 we support GHC 6.8, GHC 6.10 and GHC 6.12. We typically require support for the version of GHC that is in Debian Stable. This may change soon, see Policy. We also like code that works on windows.

Things you should relax about

• Haskell style

  • We understand that not every developer is an expert Haskeller --we certainly are not! -- so do not worry about having perfect Haskell. For that matter, some of us like to think of darcs as a hands-on training programme for new Haskell developers. So send us some patches and we will comment on them. Watch out though! There might be a few iterations asking for amendments.

• Platform compatibility

  • We like portable code but we know not every developer has access to a fleet of machines to run tests on. That's why we check all accepted patches with automated build bots that run the comprehensive test suite on many platforms including windows.

General principles

At the time of this writing (2008-10), darcs development culture seems to operate along two general principles:

• Slowly but surely (haste makes waste)

  • There is a time and place for agile development, even in the darcs project. That said, darcs tends to adopt a slower and more deliberate approach to making changes. We like to do things gradually, so be prepared to send your changes in smallish batches, of around 5 or so patches at a time. No hard and fast rules here, just something to get a feeling for

• Get things right the first time

  • Review first, apply later: All patches are reviewed before they go into the main repository.
  • Amend first, apply later: If we request modifications to your patches, we usually like them to be in the form of amended patches (as opposed to additional patches). Sometimes this is very impractical if you have a lot of changes, and we will make exceptions to this general rule to keep things running smoothly. But be aware of this attitude!

Patch tracker

Darcs now uses a patch tracker, which can be found at http://bugs.darcs.net/patch - when you use darcs send to submit your patches they will end up there automatically. See PatchTracker for more information on this.