[PATCH v3 5/5] Documentation: add caveats about I/O buffering for check-{attr,ignore}

On Thu, Apr 11, 2013 at 11:09:28AM -0700, Junio C Hamano wrote:

I very much appreciate the excellent job you do as maintainer; your attention to detail results in an incredibly high quality project. However I do occasionally find your communication style unnecessarily abrasive. Maybe that's just me.

I am sorry for wasting five minutes of your time. A non-reflowed version is included inline below, and also at:

    https://github.com/aspiers/git/compare/master...git-annex-streaming

It would have been slightly simpler, yes. It did occur to me not to re-flow it, but then one of the lines ended up noticeably shorter, and as it was a short paragraph, I estimated that you would prefer it re-flowed. Clearly I was wrong - not the first time, and it won't be the last either, since I'm just a flawed human being trying to do my best in the time available. The question then arises: how uneven does a paragraph's right margin have to be in order to justify re-flowing? I could not find any guidelines in SubmittingPatches or CodingGuidelines regarding re-flowing of documentation. With hindsight, I can now see that it would have been better to skip it on this occasion, or at least keep the re-flow as a separate commit.

So I apologise again for the mistake, but don't you think it would have been far more pleasant if instead you'd worded your email something like this?

    Thanks for the patches.  I notice that you unnecessarily re-flowed
    the latter half of the GIT_FLUSH paragraph; unfortunately this
    meant I had to spend a few extra minutes on the review and almost
    missed that "commit-oriented" is no longer applicable.  In future,
    please avoid re-flowing text where possible.

Fortunately I'm not the sensitive sort, but I imagine that there are others in this community who might be discouraged from contributing for fear of being on the receiving end of sentences which end with phrases such as "[...] is very much unappreciated X-<." Please don't underestimate the human factor; common courtesy can make a big difference.

Thanks, Adam

-- >8 --
Subject: [PATCH v3 5/5] Documentation: add caveats about I/O buffering for
 check-{attr,ignore}

check-attr and check-ignore have the potential to deadlock callers which do not read back the output in real-time. For example, if a caller writes N paths out and then reads N lines back in, it risks becoming blocked on write() to check-*, and check-* is blocked on write back to the caller. Somebody has to buffer; the pipe buffers provide some leeway, but they are limited.

Thanks to Peff for pointing this out:

    http://article.gmane.org/gmane.comp.version-control.git/220534

Signed-off-by: Adam Spiers <git@adamspiers.org>
---
 Documentation/git-check-attr.txt   | 5 +++++
 Documentation/git-check-ignore.txt | 5 +++++
 Documentation/git.txt              | 7 ++++---
 3 files changed, 14 insertions(+), 3 deletions(-)