• DeveloperGettingStarted

DeveloperGettingStarted

under construction:

While DeveloperTips is a loose collection of tips, this page is intended to be a structured guide for newcomers. There may be overlappings which have to factored out. Be bold!

italic text is meta information for editors as long as this page is under heavy construction.

Since darcs is written in haskell, interested developers will find it difficult to dive in the code. Here we explain how the project is structured and where you can find more infos (e.g. on haskells build system etc.)

Getting the Source

• Info on different branches, repositories etc.

• how to deal with patches, where to send ...

...

Overall Structure of Darcs

• src contains main modules and some utilities

  • Crypt ??

  • Darcs contains core modules like Repository etc

    • Commands contains all the commands that can be executed via darcs (e.g. diff, pull, get)

    • Patch contains core code to perform patching (apply, commute etc)

    • Repository contains utilities for repo-handling

  • win32 platform dependent code for windows

    • System

      • Posix

    • sys

Important make targets

darcs comes with a standard makefile. Some interesting targets are:

• make tags

• make darcs versus make darcs_p, as of 2008-10 you can have both normal and profile builds at the same time.

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

• make api-doc 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:

  • make api-doc-with-source as above, but also links to colourised source code. Requires HsColour.

  • make hoogleindex generates hoogle/default.hoo, a hoogle index you can use to search code by function name and type signature. Usage: hoogle --data=hoogle/default somepattern. Requires Hoogle.

  • make hoogleweb configures a web interface for the above, similar to http://haskell.org/hoogle. Requires a configured and patched hoogle source tree to work well (see darcs makefile).

  • make api-doc-frames brings the above (haddock docs, colourised source, hoogle search) together in a framed web interface, similar to http://joyful.com/repos/darcs-stable/api-doc.

• make continuous or make ci (continuous integration) watches your haskell source files and recompiles and runs darcs whenever you save an edit. This can be very useful when working on code to get rapid feedback from ghc; leave it running in a side window, or in an emacs compilation/comint-mode buffer. Requires a patched version of sp from http://joyful.com/repos/searchpath (see http://searchpath.org for more.)

• make maintainer-clean If something doesn't work after pulling changes try this.

• ... more targets ...

Literate Haskell

Darcs is written in literate haskell. That means that the haskell code is embedded into the (latex-) documentation. The manual is written that way.

Integrated Development Environments

Here some notes how to configure your workspace in your favorite IDE. Use make tags to generate hasktags that can be used with your editor of choice.

• emacs
  • M-x tags, then use M-. to find identifiers in the code.
• vim ... ?
• eclipse ... ?

Sending your patches to darcs.net

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.

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
  • 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
    • Tell us if you have future work in this line

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

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

  • 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 2008-10 we support GHC 6.6 and GHC 6.8. We typically require support for the version of GHC that is in Debian Stable. 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!

Links

• Read Haskell

• api-doc with Haddock