Re: Patch to contributing instructions

[Gerald Pfeifer <pfeifer at dbai dot tuwien dot ac dot at>]

On Sun, 14 Oct 2001, Joseph S. Myers wrote:
> Index: contribute.html
> ===================================================================
> RCS file: /cvs/gcc/wwwdocs/htdocs/contribute.html,v
> retrieving revision 1.37
> diff -u -r1.37 contribute.html
> --- contribute.html	2001/10/09 21:41:32	1.37
> +++ contribute.html	2001/10/14 18:34:16
> @@ -22,8 +22,10 @@
>    href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
>    Standards</a>.  There are also some <a
>    href="codingconventions.html">additional coding conventions for
> -  GCC</a>.  Submissions which do not conform to the standards will be
> -  returned with a request to reformat the changes.</p>
> +  GCC</a>; these include documentation and testsuite requirements as
> +  well as requirements on code formatting.  Submissions which do not
> +  conform to the standards will be returned with a request to reformat
> +  the changes or otherwise fix problems in them.</p>

"...will be returned with a request to address any such problems"

>  <dt>Documentation</dt>
>  <dd>
> -If the patch adds a new command line option, the patch must also add
> -documentation for that option to the GCC manual.  Similarly, if it
> -changes the behavior of an existing command line option or other
> -documented behavior, the patch must update the documentation.
> -Documentation is also required for any changes or additions to the
> -parts of the front-end and back-end interfaces documented in the
> -manual (such as new target macros).
> +See the requirements of the <a href="codingconventions.html">GCC
> +coding conventions</a> about documentation.
>  </dd>

I think we can just remove the entires subsection, as we refer to the
GCC coding conventions anyway?

>  <dt>Testcases</dt>
>  <dd>
> -It is strongly recommended the patch should add testcases for any new
> -features added and any bugs fixed to the testsuite, if not already
> -there.  (You will of course have tested any new features you added, so
> -this is simply a matter of writing your tests in a suitable form for
> -inclusion in the testsuite.)
> +If you cannot follow the recommendations of the <a
> +href="codingconventions.html">GCC coding conventions</a> about
> +testcases, you should include a justification for why adequate
> +testcases cannot be added.  Normally, you will of course have tested
> +any new features you added, so following the recommendations is simply
> +a matter of writing your tests in a suitable form for inclusion in the
> +testsuite; but in some cases tests may have copyright problems and it
> +may not be practicable to create a test that can be included, or the
> +test harnesses may not be suitable for testing for a particular bug.
>  </dd>

Personally, I'd just ommit everything after "Normally, you will..." to
keep the instructions shorter, and as there is no "hard" additional
information there, but I do not fell that strongly about it.

>  <dt>ChangeLog</dt>
>  <dd>
>  A ChangeLog entry as plaintext; see the various ChangeLog files for
> -format and content.<br>
> -Note that, unlike some other projects, we do require ChangeLogs also for
> -documentation (i.e., .texi files).  They are not required for updates to
> -the web pages.
> +format and content, and the <a href="codingconventions.html">GCC
> +coding conventions</a> and <a
> +href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
> +Standards</a> for futher information.  The ChangeLog entries should be
> +plaintext rather than part of the patch since the top of the ChangeLog
> +changes rapidly and a patch to the ChangeLog would probably no longer
> +apply by the time your patch is reviewed.
>  </dd>

futher -> further

>  <dt>Bootstrapping and testing</dt>
> @@ -101,11 +110,28 @@
>  else, use &quot;<code>diff -c3p OLD NEW</code>&quot; or
>  &quot;<code>diff -up OLD NEW</code>&quot;.  If your version of diff
>  does not support these options, then get the latest version of GNU
> -diff.
> +diff.  Patches against current development (mainline CVS) are
> +preferred to patches against releases, unless your patch is intended
> +as a candidate for the release branch, but smaller changes against
> +releases may still be usable.
>  </dd>

Let's omit the "but smaller changes" part.

Thanks,
Gerald
-- 
Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/