It is vital that contributors have a clear idea how to make darcs patches that
are likely to get accepted, and what to expect afterwards.  See
http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial
for inspiration

+1, excellent idea.

This is a good idea, and to help the people that work on this I've
pooled together some of what I know is out there:

http://wiki.darcs.net/DarcsWiki/DeveloperFAQ
http://wiki.darcs.net/DarcsWiki/DeveloperTips  (this page recommends
liftM, please update to fmap as David has said he prefers fmap, as
it's one less import).
http://wiki.darcs.net/DarcsWiki/DeveloperGettingStarted

all of the above are linked in the Development section here:
http://wiki.darcs.net/DarcsWiki

The main problem with what is there is that while we try to explain
code/coding to people, we have very little on how to submit patches
that will have a high probability of getting accepted.  We also have
nothing on what to do when your patches are rejected.

Policies we should encourage:
1) We could rate the quality of patches in this order:
  * includes at least one test
  * related to a ticket in the bug tracker
  * comes with explanation/justification
  * includes documentation
  * makes a change to darcs
2) Discussion/consensus prior to implementation should be preferred
3) Establish which parts of darcs can be updated with little review
4) Establish which parts of darcs require extensive review

Taking advice from XMonad, (3) and (4) could come about more naturally
as we factor darcs into separate libs.  But, we could also start today
by just declaring that modules in X directory require heavy review and
Y doesn't.  We have already started this process by allowing Eric to
fast track documentation changes.

The meta goal of all this work could be summed up as follows:
We need to build confidence that people can easily contribute to darcs
in such a way that their hard work
will be accepted.

Thanks,
Jason

Good precisions, thanks.

On Mon, Oct 27, 2008 at 18:30:14 -0700, Jason Dagit wrote:
> http://wiki.darcs.net/DarcsWiki/DeveloperTips  (this page recommends
> liftM, please update to fmap as David has said he prefers fmap, as
> it's one less import).

Done.

See also
  http://lists.osuosl.org/pipermail/darcs-devel/2006-January/003934.html
from Juliusz when he was starting to get to grips with being unstable
maintainer.  Some of our practices have changed since then, but this may
be a good basis for such work.

It's worth considering just making this document part of the
  http://wiki.darcs.net/DarcsWiki/DeveloperGettingStarted
link that Jason found.

Ok, I have started work by extending Simon's technical guide to include some of
our cultural norms here:

http://wiki.darcs.net/index.html/DeveloperGettingStarted

I would urge other developers to help us flesh it out.  When we have this in a
somewhat reasonable state, we should probably ask David to have a look.

Status update (about a year and a half after this bug was first opened)
We now have http://wiki.darcs.net/Development/GettingStarted

Let's go through Jason's suggestions in more detail.

I'm going to mark this resolved, because I think we've pretty much
reached a point where the guide above is going to always be gently
in progress.

On Tue, Oct 28, 2008 at 01:30:38 +0000, Jason Dagit wrote:
> 1) We could rate the quality of patches in this order:

I don't understand the ordering exactly, and but I think our
"conventions" and "things we like" section addresses this to
some extent

>   * includes at least one test

We say that we'd like test cases for new functionality and
also talks about how to deal with bugfix patches.

>   * related to a ticket in the bug tracker

We talk about the 'resolve issueXXX' convention (this isn't
what Jason is referring to, I suspect), but it's worth
mentioning.

>   * comes with explanation/justification

We say (in "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
    * If you have future work in this line

>   * includes documentation

We say:

* 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

>   * makes a change to darcs

Again, this depends on what Jason means.

> 2) Discussion/consensus prior to implementation should be preferred

Addressed in a bullet point about "Collaboration"

> 3) Establish which parts of darcs can be updated with little review
> 4) Establish which parts of darcs require extensive review
> 
> Taking advice from XMonad, (3) and (4) could come about more naturally
> as we factor darcs into separate libs.  But, we could also start today
> by just declaring that modules in X directory require heavy review and
> Y doesn't.  We have already started this process by allowing Eric to
> fast track documentation changes.

These are nice, but I think it will emerge naturally as the Darcs library
improves.

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9