Re: Dates in Commits and other issues of style (Re: [RFC 2/5] Pretty Print: show tz when using DATE_LOCAL)

Miles Bader [off-list ref] writes:

Michael Witten [off-list ref] writes:

quoted

and I feel like
you are now
nitpicking.

Wait, isn't nitpicking his job?!

Enforcing consistency is one of the important tasks the maintainers do in
their projects.  Besides ensuring that the intent of the change each patch
brings to the codebase is good, that the log entry describes the change in
a useful way for future readers, and that the patch correctly implements
the described change, we also need to make sure that the resulting code
matches the style of the surrounding code, and the style, structure and
tone the log messages are delivered in a consistent voice.  Otherwise it
would quickly get very tiring when you have to dig into the history of the
codebase.  The code and the history are read a lot more often than are
written.

When a casual and occasional contributor sends in a good change whose only
sin is style violation, I do not mind touching up its proposed commit log
message or the patch text, and I often do.

But I expect contributors who return here often to be more considerate
than one-time contributors, and that is why I give style reminders.

The purpose of the style reminder is so that they can help me and other
reviewers concentrate on the substance (Is what it does good? Is it
explained well? Is it implemented well?) without having to spend
unnecessary time fixing the form (Does the new code fit well with the
surrounding code? Does the message flow well in "git log" and easy to
understand?) when they submit their changes the next time.

Please do not mistake a style reminder as an opportunity to promote your
own style that would not match what we have established here.  I could
make a black-list of people I should avoid giving style reminders and
instead fix all of their submissions silently, because giving style
remainders to them will waste people's time by creating a discussion
thread like this one.

I really wish I do not have to do so.

Such an arrangement would not scale.  Given two sets of patches with equal
goodness in substance, if one also matches our style and the other
deliberately asks me to spend extra time to whip it into our style, the
latter naturally has to be assigned a lower priority.  After all, there is
only 24 hours in a day, and my time is better spent on substance not form,
and definitely not on responding to quibblings about styles.

The only two "workable" solutions are either (1) everybody tries to be
consistent with the project's style, or (2) allow everybody to stick to
their own style, making the resulting code and history unpleasant to read.

I'd be failing the community if I took the latter approach.

Junio C Hamano [off-list ref] writes:

Enforcing consistency is one of the important tasks the maintainers do in
their projects.  Besides ensuring that the intent of the change each patch
brings to the codebase is good, that the log entry describes the change in
a useful way for future readers, and that the patch correctly implements
the described change, we also need to make sure that the resulting code
matches the style of the surrounding code, and the style, structure and
tone the log messages are delivered in a consistent voice.  Otherwise it
would quickly get very tiring when you have to dig into the history of the
codebase.  The code and the history are read a lot more often than are
written. [...]

This information should be put e.g. in SubmittingPatches, or
CodingGuidelines, or MaintNotes, isn't it?

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Jakub Narebski [off-list ref] writes:

Junio C Hamano [off-list ref] writes:

quoted

Enforcing consistency is one of the important tasks the maintainers do...

This information should be put e.g. in SubmittingPatches, or
CodingGuidelines, or MaintNotes, isn't it?

The above "we value consistency" should be already inferrable by reading
SubmittingPatches and CodingStyle in reverse?  If it were up to the
contributors to ignore them, there is no point to have these guides to
begin with.

If we want to keep these words somewhere, I think the place to put it
would probably be the Policy section of Doc/howto/maintain-git.txt.