Getting the Source

There are three repositories that we use for new Darcs development:

and some older release branches:

As a patch author, you are most likely interested in the screened repository, which you can fetch with darcs get --lazy http://darcs.net/screened. The typical flow of patches is from your local repo, to the patch tracker, to screened, then reviewed and finally the release branch. You should consider your patch as having been accepted once it makes it into reviewed.

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 -a
cabal build
cabal test
cabal install

The impatient may prefer:

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

For a faster build, you can add the flag -f-library to cabal install. This disables library building.

Testing Your Work

The default test hook will try to build Darcs and run the functional tests every time you record a patch. You can use –no-test if you’re in a hurry, but please try to test sometimes!

Sending your patches

Congratulations! You’ve written some lovely darcs 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 to submit your patches they will end up there automatically. See PatchReview for more information on this.

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/screened. This is the first repository that patches will land in, before moving to the main http://darcs.net.

• 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 darcs send troubleshooting info.

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

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

• GHC version compatibility

  • We typically require support for the last two stable versions of GHC. As of 2010-11 we support GHC 6.10 and GHC 6.12. See also Policy.

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.
  • Apply first, refine later: If we request modifications to your patches, just send them as follow-up patches, no need to amend.

Important cabal targets

darcs comes with a standard Cabal file. Some interesting targets are:

• cabal install darcs --enable-library-profiling --enable-executable-profiling lets you have profile builds (along with the normal ones) at the cost of quadrupling compile time

• Think your code is ready? Try cabal test to see if you pass all of the tests on your machine!

• cabal haddock generates html reference documentation for all modules, types and functions in darcs. This requires at least haddock 2.0. Also, there is a family of related targets for fancier docs:

We also have a small makefile for little helpers, right now, building tags and user documentation:

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.

Adding Documentation

Remember to add interesting information to the wiki and bugs to the bug tracker.

• Darcs Bug Tracker (Creating an account: http://bugs.darcs.net/user?@template=register )
• Darcs Wiki (here!) (Creating an account: http://wiki.darcs.net/_login )
• Contribute to the darcs manual
• Add notes on process here. <!>

Links

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