[darcs-devel] How to submit patches that make your maintainer happy

Juliusz Chroboczek Juliusz.Chroboczek at pps.jussieu.fr
Fri Jan 13 13:28:15 PST 2006


Dear Darcs contributors,

I'm slowly starting to get the hang of that maintaining a branch
business, so I thought I'd write up how you can increase my level of
happiness.  Of course, whether you actually want me to be happy is a
matter of local policy.

In the following, I use ``commit'' to mean ``pull into the public
darcs-unstable branch on darcs.net''.


1. Send patches and comments through the public channels

Send patches using ``darcs send'' against darcs-unstable, or as
attachments to Darcs-Devel.  Send questions about Darcs and comments
about patches to Darcs-Devel or Darcs-Users.

If you send me personal mail that isn't CC'd to Darcs-Devel, it will
get sorted into the wrong mailbox unless you include the word ``Darcs''
somewhere in the subject line.


2. Use proper darcs log messages

A Darcs log message consists of two parts: the so-called ``patch
name'' (think of it as a subject line) and the ``long description''
(think of it as a message body).

The patch name should be a human-readable string, with proper
capitalisation and punctuation.  It should be concise (no longer than
75 characters), and understandable in a rush.

  * ``Fix handling of paths containing colons'' is good.
  * ``Fix issue 73'' is bad.
  * ``Fix my previous patch'' is sort-of okay, but ``Fix my patch
    called ...'' is better.
  * ``Fix merge conflicts'' is okay, as the conflicting patches
    fixed can be worked out from the repository.

The long message is optional.  If included, it should consist of lines
limited to 75 characters, and reasonably concise -- 5 lines is
definitely okay, 25 is stretching it.  It should only contain
information that is to be included in the repository and stay there
for ever and ever, as opposed to information that is only temporary --
the latter should go into the bundle description (see below).

It is up to you whether to use a long message or comments in the
source; my personal opinion is that much of the time comments in the
source are more appropriate.


3. Use patch bundle descriptions to tell me what to do with the patch

When you send patches to the list, you send data structures known as
``patch bundles''.  The patch bundle can be accompanied with a
description that will be discarded when the patches get committed.

You can include a description either by using the option
``--edit-description'' to ``darcs send'', or by editing the body to
which you attach a bundle by hand in your editor

If you send patches that you think are not ready for inclusion, you
must say so in the comment.  If you send patches that you think are
ready for inclusion, it is helpful (but not actually necessary) to say
so in the comment.

Do not include such information in the long message of a patch -- a
``not quite ready'' patch might get committed after all, it would be
silly to have a log message that says that the patch should not be
committed.


4. Send self-contained patches

Darcs makes it easy to send patches that are logical units; please do
so.  For example, don't send me a patch that both implements a new
feature and updates the test suite; send a bundle of two patches
instead.

Sending a logical unit in multiple patches is okay (e.g. ``partial
implementation of foo'' followed by ``complete the implementation of
foo'').  If you understand Darcs, you can avoid that by *carefully*
using amend-record.


5. Review patches for me

If you feel you are competent to review a patch you see on darcs-devel,
don't hesitate to express your opinion (publicly, not by private
e-mail!).  If you think a patch is okay, a one-liner saying ``please
commit'' or ``okay with me'' is enough, but longer explanations are of
course welcome and will be read carefully.

Reviews of Windows-specific code and of Perl and shell code are
particularly helpful, as I'm illiterate in those areas.  But please
don't assume that your contribution is useless just because it doesn't
fall in the above categories: even reviews of completely trivial
patches increase my happiness and your karma.


6. Resend patches after 12 days

I try to go through the pending patches every week.  If you haven't
heard from me roughly 12 days after sending a patch, send the patch
again.  You are welcome to include profanity in the bundle description,
but not in the log message.


                                        Juliusz




More information about the darcs-devel mailing list