On Jan 13, 2006, at 1:28 PM, Juliusz Chroboczek wrote:
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.
Thanks Juliusz. This list really helps. I had already created the resend of my patches before I read this, so I think perhaps I still violated a policy or two, but my patches should be much better. And just for the record, I didn't think all my patches were rejected, and I know you have more than darcs maintenance in your life. In the future I'll follow your 12 day rule and try to comment on patches when I can (as well as follow the other conventions).
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.
Other guides around the internet strongly suggest linking commit logs to bug trackers. So my suggestion here is that
* ``Fix handling of paths containing colons (issue73) Is even better.
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.
Excellent point, and I'm working on getting haddock to be a happy part of the build system. So, my advice here is to comment using haddock markup that way it will appear in the the api docs.
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.
I'm guilty of this is my most recent resend. I commented that one of the patches needs more testing (also mentioned it in the email). I'd rather not recreate that patch, but I will if you feel strongly about it. (I'll definitely avoid this is the future).
Thanks, Jason _______________________________________________ darcs-devel mailing list [email protected] http://www.abridgegame.org/cgi-bin/mailman/listinfo/darcs-devel
