make it more explicit that design discussions should happen before code reviews

R=rsc
CC=golang-dev
https://golang.org/cl/180075

2 files changed, 26 insertions, 2 deletions

diff --git a/doc/code.html b/doc/code.html
index 6e32a3d309..5c60222aab 100644
--- a/doc/code.html
+++ b/doc/code.html
@@ -12,10 +12,11 @@ It assumes you have installed Go using the
 <p>
 Before embarking on a change to an existing
 package or the creation of a new package,
-it's a good idea to send mail to the <a href="http://groups.google.com/group/golang-nuts">mailing list</a>
+be sure to send mail to the
+<a href="http://groups.google.com/group/golang-nuts">mailing list</a>
 to let people know what you are thinking of doing.
 Doing so helps avoid duplication of effort and
-enables discussions about design before much code
+enables discussions about design before any code
 has been written.
 </p>
 
diff --git a/doc/contribute.html b/doc/contribute.html
index d4bf667a25..ca24973c5c 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -11,6 +11,29 @@ have <a href="code.html">written and tested your code</a>.
 see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
 </p>
 
+<h2 id="Design">Discuss your design</h2>
+
+<p>
+The project welcomes submissions but please let everyone know what
+you're working on if you want it to become part of the main repository.
+</p>
+
+<p>
+Before undertaking to write something new for the Go project, send
+mail to the <a href="http://groups.google.com/group/golang-nuts">mailing
+list</a> to discuss what you plan to do.  This gives everyone a
+chance to validate the design, helps prevent duplication of effort,
+and ensures that the idea fits inside the goals for the language
+and tools.  It also guarantees that the design is sound before code
+is written; the code review tool is not the place for high-level
+discussions.
+</p>
+
+<p>
+In short, send mail before you code.
+And don't start the discussion by mailing a change list!
+</p>
+
 <h2 id="Testing">Testing redux</h2>
 
 <p>