To PR Senders

[Bill Moran]

Marc Fonvieille <blackend at freebsd.org> wrote:

> Hello,
> 
> As everyone knows, sending a PR is the best way to help us to fix a
> documentation issue.  When you send a PR and you have a patch to fix the
> problem, you should *attach* the patch with the PR and *not* just provide a
> URL.
> 
> With a URL, the PR database will not contain your submission, it will
> be difficult for us to read the PR, it will be difficult for us to work
> on your submission via PR feedback, etc.  So, please attach your
> patches.
> 
> Thanks for the listening :)

There is some problematic ambiguity to this request.

Section 4.3 of the article on submitting problem reprts:
http://www.freebsd.org/doc/en_US.ISO8859-1/articles/problem-reports/pr-writing.html
states
"Also note that while including small patches in a PR is generally all
right--particularly when they fix the problem described in the PR--large
patches and especially new code which may require substantial review
before committing should be placed on a web or ftp server"

While I agree with everything that's been stated here (both in your email
Marc, as well as the article) the question for anyone submitting a PR
becomes: "Based on these recommendations, do I attach it or post it?"

The best advice I've heard so far was (unfortunately) relegated to PS
status in your email:

> PS: Of course do not send your 1MB patch :))

So, now I know that patches of 1M or larger are not attached, while those
of smaller size may(?) be attached ;)  Fact is, I don't _really_ know
what the upper limit is (size-wise) for attaching vs. posting.  And the
reference to "new code/substantial review" is (unfortunately) even more
ambiguous!

I guess what I'm saying is that for someone like myself (who has and
intends to continue submitting patches, but has never been on the
other side of PR handling) it's difficult to know what the best way
to submit a patch is.  My goal as a patch submitter is to make the
job of the comitter as easy as possible, so he/she can focus on the
_content_ of my patch, not the steps required to extract and unmangle
it.

I don't have the knowledge to make exact recommendations, but perhaps
a documented rule of thumb along these lines would help:

"Patches in excess of 200k, or which contain over 50 lines of completely
new content, should not be attached to the PR, but should be placed on
an ftp/web server and the URL included.  Patches below these limits
should always be attached to the PR."

I understand that it may be difficult to reach a consensus on exactly
what limits to set, but I think it would make things a little clearer
for folks like me.

Hope these musings are useful.

-- 
Bill Moran
Potential Technologies
http://www.potentialtech.com