[darcs-users] darcs patch: Resolve issue1093: warn about ugly patch... (and 1 more)

Trent W. Buck trentbuck at gmail.com
Tue Feb 3 23:56:54 UTC 2009


My understanding of the patch name is that it acts like the Subject
header field in an email or nntp post -- i.e. that it's a SENTENCE that
concisely describes the patch/mail/post in question, so that the reader
does not have to read the long description unless they want extra
detail.  Based on this assumption,

  - If it's not a sentence, it's harder to read -- particularly if you
    concatenate several together (e.g. when auto-generating "changes
    since <tag>" logs).

  - If the sentence is very short, it clearly isn't descriptive enough.

  - If the sentence is very long, it clearly contains too much
    information (information which should be in the long description
    (which is analogous to a mail/post body).

Politely pointing out to the user when it looks like they have violated
these corrollaries is analogous to -Wall and/or -pedantic in GCC.  IME
making those switches on by default for a project encourages the
developers to avoid introducing warnings, and this is helpful later on
when trying to find an actual problem.

>From replies to this thread, it would seem that people disagree with my
original assumption -- that the patch name should be a concise synopsis
-- and thus disagree with the corrollaries also.  This is distinct from
merely disagreeing with the heuristics used (e.g. "ten" in "under ten
characters is clearly too short"), which I expected to need refinement.

> Since there's an issue number, I presume there's a real issue with  
> these "strange" names.
>
>>>  MAYBE - warn on overly long patch names (as this could cause some
>>>          concrete practical problems for other folks, wrt wrapping)
>
> I use overly long patch names pretty frequently.  In one case it is
> because I don't have working text editor integration on Windows, so it
> is inconvenient to write a patch name with more than one line in it.

Patch names cannot contain newlines.

If you're saying that technical problems encourage to stick a long
description into the patch name... that's the precise behaviour I want
to gently discourage.  In fact IIRC it was one of your (zooko's) patches
to the Darcs repo that annoyed me enough in this respect to file the
wishlist bug.

I think one of the reasons you're encouraged to do this is because Darcs
does not make it very obvious that the patch name and the long
description are *fundamentally* distinct data, because Darcs nearly
always prints them on adjacent lines with no separator.  It's thus very
natural to write something like this (and indeed, I am guilty of it):

           Name: Fix a bug in foo/bar/baz.c,
    Description: where I was not properly freeing after a malloc.

But this can be confusing when generating nonstandard output formats.
For example, the old Perl script for graphing patches using Graphviz
shows the name, but not the long description.  As the above case ends in
a comma, the reader looking at that node in the graph would be confused
as to where the rest of the sentence has gone.

As to the lack of editor integration on Windows, I would hope that the
proposed warning messages would politely remind you to address the
problem (in your Copious Free Time ;-)).  Now that the it's been raised,
I'd like to know more about it.  Is this problem something that affects
many/most Darcs-on-Windows users?  (If so, please file a bug report.)

Is is something Darcs can address with code?  If not, is it something we
can address with documentation?  For example, maybe we can document on
the wiki how to get Darcs to fire up a bunch of preferred editors on
Windows (eclipse, notepad, etc.), or how to set the "default editor" on
Windows.

> Also, as a matter of style I prefer paragraphs per line. [...]

I don't think that's relevant, as we've been talking about the patch
name, rather than the long description.




More information about the darcs-users mailing list