Re: Patch to contributing instructions

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

Here's the version I've committed.

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/16 11:49:30
@@ -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 address
+  any such problems.</p>
 
 
 <h2>Copyright Assignment</h2>
@@ -53,35 +55,31 @@
 <dt>A description of the problem/bug and how your patch addresses it.</dt>
 <dd>
 For new features a description of the feature and your implementation.
+For bugs a description of what was wrong with the existing code, and a
+reference to any previous bug report (in the <a href="gnats.html">GCC
+GNATS database</a> or the <a
+href="http://gcc.gnu.org/ml/gcc-bugs/";>gcc-bugs archives</a>) and any
+existing testcases for the problem in the GCC testsuite.
 </dd>
 
-<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).
-</dd>
-
 <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.
 </dd>
 
 <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 further 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>
 
 <dt>Bootstrapping and testing</dt>
@@ -101,11 +99,27 @@
 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.
 </dd>
 
 </dl>
 
+  <p>Don't mix together changes made for different reasons.  Send them
+  <em>individually</em>.  Ideally, each change you send should be
+  impossible to subdivide into parts that we might want to consider
+  separately, because each of its parts gets its motivation from the
+  other parts.  In particular, changes to code formatting to conform
+  to coding standards are best not mixed with substantive changes,
+  because that makes it difficult to see what the real changes are.
+  (In the case of a very large reorganization of code, it may make
+  sense to separate changes even further to make it clearer what has
+  changed; for example, by first sending structural changes that make
+  subsequent changes easier but do not change GCC's behavior, then new
+  code, then the changes that actually make use of the new code and
+  change GCC's behavior.)</p>
+
   <p>We accept patches as plain text (preferred for the compilers
   themselves), MIME attachments (preferred for the web pages),
   or as uuencoded gzipped text.</p>
@@ -125,6 +139,14 @@
   Patches can occasionally fall through the cracks. Please be sure to
   include the URL of the entry in the mailing list archive of the original
   submission.</p>
+
+  <p>Patches to the standard C++ library (libstdc++-v3), and its web
+  pages, and discussion of such patches, should go to <a
+  href="mailto:libstdc++@gcc.gnu.org";>libstdc++@gcc.gnu.org</a> as
+  well as to gcc-patches.  Patches to the Java library (libgcj) should
+  go to <a
+  href="mailto:java-patches@gcc.gnu.org";>java-patches@gcc.gnu.org</a>
+  instead of gcc-patches.</p>
 
 </body>
 </html>
Index: codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.7
diff -u -r1.7 codingconventions.html
--- codingconventions.html	2001/09/12 21:24:49	1.7
+++ codingconventions.html	2001/10/16 11:49:30
@@ -11,19 +11,53 @@
 beyond those in the <a
 href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
 Standards</a>.  Some existing code may not follow these conventions,
-but they should be used for new code.  If changing existing
+but they must be used for new code.  If changing existing
 code to follow these conventions, it is best to send changes to follow
 the conventions separately from any other changes to the code.</p>
 
 
+<h2>Documentation</h2>
+
+<p>Documentation, both of user interfaces and of internals, must be
+maintained and kept up to date.  In particular:</p>
+
+<ul>
+
+  <li>All command-line options must be documented in the GCC manual.</li>
+
+  <li>Any change to documented behavior (for example, the behavior of
+  a command-line option or a GNU language extension) must include the
+  necessary changes to the manual.</li>
+
+  <li>All target macros must be documented in the GCC manual.</li>
+
+  <li>The documentation of the <code>tree</code> and RTL data
+  structures and interfaces must be kept complete and up to date.</li>
+
+  <li>In general, the documentation of all documented aspects of the
+  front-end and back-end interfaces must be kept up to date, and the
+  opportunity should be taken where possible to remedy gaps in or
+  limitations of the documentation.</li>
+
+</ul>
+
+
 <h2>ChangeLogs</h2>
 
 <p>GCC requires ChangeLog entries for documentation changes (see <a
 href="http://gcc.gnu.org/ml/gcc-bugs/1998-03/msg00564.html";>message</a>),
-though for changes to the GCC web pages (as opposed to the
+though for changes to the GCC web pages (as opposed to the java and
 libstdc++-v3 ones) there is no appropriate ChangeLog file and the CVS
 logs suffice.</p>
 
+<p>See also what the <a
+href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
+Standards</a> have to say about what goes in ChangeLogs; in
+particular, descriptions of the purpose of code and changes should go
+in comments rather than the ChangeLog, though a single line overall
+description of the changes may be useful above the ChangeLog entry for
+a large batch of changes.</p>
+
 <p>There is no established convention on when ChangeLog entries are to
 be made for testsuite changes; see messages <a
 href="http://gcc.gnu.org/ml/gcc/2000-09/msg00287.html";>1</a> and <a
@@ -52,12 +86,17 @@
 <code>bcmp</code>, <code>bcopy</code>, <code>bzero</code>,
 <code>index</code> and <code>rindex</code>; see messages <a
 href="http://gcc.gnu.org/ml/gcc/1998-09/msg01000.html";>1</a> and <a
-href="http://gcc.gnu.org/ml/gcc/1998-09/msg01127.html";>2</a>.  Note
-if changing the form used in existing code that care must be taken
-over the different argument order used by <code>memcpy</code> and
-<code>bcopy</code>, and that <code>bcopy</code> is equivalent to
-<code>memmove</code> though in most cases <code>memcpy</code> is the
-appropriate replacement.</p>
+href="http://gcc.gnu.org/ml/gcc/1998-09/msg01127.html";>2</a>.  The
+older functions must no longer be used in GCC; apart from
+<code>index</code>, these identifiers are poisoned to prevent their
+use.</p>
+
+<p>Machine-independent files may contain conditionals on features of a
+particular system, but should never contain conditionals such as
+<code>#ifdef __hpux__</code> on the name or version of a particular
+system.  Exceptions may be made to this on a release branch late in
+the release cycle, to reduce the risk involved in fixing a problem
+that only shows up on one particular system.</p>
 
 
 <h2>Makefiles</h2>
@@ -67,6 +106,12 @@
 
 
 <h2>Testsuite Conventions</h2>
+
+<p>Every language or library feature, whether standard or a GNU
+extension, and every warning GCC can give, should have testcases
+thoroughly covering both its specification and its implementation.
+Every bug fixed should have a testcase to detect if the bug
+recurs.</p>
 
 <p>The testsuite READMEs discuss the requirement to use <code>abort
 ()</code> for runtime failures and <code>exit (0)</code> for success.

-- 
Joseph S. Myers
jsm28@cam.ac.uk