Add new text about avoiding email mangling; about backing up your work

before you submit; and considerations of when a PR is "too large".
This commit is contained in:
Mark Linimon 2005-10-20 06:45:47 +00:00
parent 06df39fac3
commit 31360fdce5
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=26086

View file

@ -462,6 +462,25 @@
on the setup of mail on &os;, see the <quote>Electronic
Mail</quote> chapter of the &os; Handbook at
<ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html"></ulink>.</para>
<para>Make sure that your mailer will not mangle the message on
its way to GNATS. In particular, if your mailer automatically
breaks lines, changes tabs to spaces, or escapes newline
characters, any patch that you submit will be rendered
unusable. For the text sections, however, we request that
you insert manual linebreaks somewhere around 70 characters,
so that the web display of the PR will be readable.</para>
<para>Similar considerations apply if you are using the web-based
PR submittal form instead of &man.send-pr.1;. Note that
cut-and-paste operations can have their own side-effects on
text formatting. In certain cases it may be necessary to use
&man.uuencode.1; to ensure that patches arrive unmodified.</para>
<para>Finally, if your submission will be lengthy, you should
to prepare your work offline so that nothing will be lost in
case there is a problem submitting it. This can be an especial
problem with the web form.</para>
</section>
<section>
@ -497,6 +516,11 @@
email programs to render tabs as spaces, which will completely
ruin anything intended to be part of a Makefile.</para>
<para>Do not send patches as attachments using
<command>Content-Transfer-Encoding: quoted-printable</command>.
These will perform character escaping and the entire patch
will be useless.</para>
<para>Also note that while including small patches in a PR is
generally all right&mdash;particularly when they fix the problem
described in the PR&mdash;large patches and especially new code
@ -507,7 +531,10 @@
the larger the patch, the harder it will be for interested
parties to unmangle it. Also, posting a patch on the web
allows you to modify it without having to resubmit the entire
patch in a followup to the original PR.</para>
patch in a followup to the original PR. Finally, large
patches simply increase the size of the database, since
closed PRs are not actually deleted but instead kept and
simply marked as <literal>closed</literal>.</para>
<para>You should also take note that unless you explicitly
specify otherwise in your PR or in the patch itself, any