2003-06-11 Nick Drochak <ndrochak@gol.cm>

	* Added Paolo's comments about CVS commits and changing code.
	Also reorganized it a bit. Hopefully this is a more logical ordering.

svn path=/trunk/mono/; revision=15283

1 files changed, 151 insertions, 68 deletions

diff --git a/web/ccvs b/web/ccvs
index 41fdbb0afe6..007b0760bcc 100644
--- a/web/ccvs
+++ b/web/ccvs
@@ -1,25 +1,45 @@
 * CVS Access
 
-	If you are an active Mono developer, you can get a CVS account
-	that hosts the Mono source code.  This web page contains
-	details about how to use the CVS server as well as the
-	policies to use it.
+	Here we describe how one obtains commit access to the CVS repository
+	and the responsibilities that come with that access privilege.
 
-	If you are not a developer, but want to track the development, please
-	see the <a href="anoncvs.html">AnonCVS</a> instructions.
+** What is CVS?
 
-	Send an e-mail to miguel with your public OpenSSH key for this
-	purpose.  Please specify if the key was generated with SSH version 1
-	or version 2.
+	Briefly, CVS is a system tool used to store and maintain files and 
+	a history of their changes over time. The Mono source code and related 
+	files are kept on a CVS server at Ximian.
 
-* Policies
+** What Access?
+
+	We mean "commit" access. This is the privilege to make permanent
+	changes to the Mono source code and related files. You need an account
+	created by the CVS server administrator in order to commit changes to
+	the files on that server.
+
+** How Does One Obtain Access?
+
+	Any active Mono developer can get a CVS account. Normally one is
+	considered an 'active' developer after sending several patches to the 
+	mailing lists and/or bugzilla for review.
 
-	Here are some policies about the use of the Mono CVS server.
+	If you are not a developer, but want to access the latest sources, 
+	please see the <a href="anoncvs.html">AnonCVS</a> instructions.
+
+	If you feel you are ready for a CVS account send an e-mail to 
+	<a href="mailto:miguel@ximian.com">miguel</a> with your public OpenSSH 
+	key for this purpose.  Please specify if the key was generated with SSH
+	version 1 or version 2. Detailed instructions are below.
+
+* Policies
 
+	It is necessary that everyone with CVS commit access respect and
+	adhere to the following rules. If you ask for and are granted CVS
+	access, you are agreeing to follow these policies.
+	
 ** Code License
 
 	If you are about to commit code to a module, the code that is
-	being commited should be released under the same license as
+	being committed should be released under the same license as
 	the code that the module has.
 
 	Check the license if you are unsure, but it is basically:
@@ -28,31 +48,102 @@
 	If in doubt, check with the maintainers of the module, or send
 	mail to mono-hackers-list@ximian.com.
 
-** Commiting code.
-
-	If you are the maintainer for a piece of code, feel free to
-	commit code, and delegate the work to others. 
-
-	Use ChangeLog entries so we can keep textual descriptions of
-	your work, and use the contents of your ChangeLog file as the
-	CVS commit message (ie, paste the contents of this into the
-	editor buffer).
-
-	If you are making changes to someone else's code, please make
-	sure you get in touch with the maintainer of that code before
-	applying patches.  You want to avoid commiting conflicting
-	work to someone else's code.
-
-	Before commiting code, you might find it useful to review your
-	patch:  Sometimes text editors change the formatting of a file,
-	and it is also good practice to check before hand.  To do so, run the
-	`cvs diff -u' command.
-
-	Please do not commit code that would break the compile to the
-	CVS, because that normally wastes everybody's time.  Two things 
+** Changing code
+
+	Even if you have CVS commit access, that doesn't mean you can change 
+	code at will in any directory or module. Directories and Namespaces 
+	have a sort of unofficial ownership. If you are not the owner of a 
+	piece of code and you want to make changes/fixes to it, there are two 
+	cases.
+	1) The change is a typo fix or a one-liner build or trivial fix. In 
+	this case almost anyone can commit (always remembering to add the 
+	proper changelog entry to explain the change). We say "almost anyone",
+	because changes to certain directories almost always should be reviewed
+	first. Such as changes to core stuff: corlib/System, System.Collections,
+	mini/, metadata/, System.IO.
+
+	2) The change is larger. In this case the patch *must* be sent to
+	mono-devel-list for review by the owner of the code and by the other
+	hackers. Always submit such patches to the list or bugzilla, although
+	you may put the owner of the code in the CC header. Hackers come and go.
+	Mailing a patch to only a personal address is a good way to get the
+	patch forgotten and missed. Plus, getting the patches reviewed as well
+	as reviewing them, is a good thing, so try to get used to it.
+
+	Note: If the patch is an addition of code and doesn't change any of the
+	existing code, the rules are slightly relaxed: there is more freedom
+	in committing such changes, if they don't interfere with the existing
+	codebase.
+
+** Owning Code
+
+	Now, how do you get to be the owner of a chunk of code? The answer is
+	simple. You wrote the code, so you're the unofficial owner. There is 
+	also another way. After sending a few patches for the code, the
+	owner (or the core developers of mono, if the owner somehow disappeared)
+	trusts you and tells you you're free to commit without getting his
+	review first.
+
+	Here is a (partial) list of namespaces/directories with their owners:
+
+        Debugger module and debug code in mono: martin
+        mcs compiler: miguel, martin, ravi
+        Reflection/Reflection.Emit: lupus, zoltan
+        IO-layer: dick
+        mini: lupus, dietmar
+        test suite: nickd (though anyone should feel free to add test cases)
+        System.IO: dick, ville
+        security stuff: spouliot
+        ilasm: jackson
+        System.Web and related: gonzalo
+        System.Xml: eno, piers
+        Remoting: dietmar, lluis
+        interop/marshal: dietmar
+        threads: dick
+
+	If you are the owner of a piece of code, feel free to commit code, and 
+	delegate the work to others. 
+
+	But, if you're not the owner of the code, committing a rewrite without
+	getting a review first is not good cvsitizenship (especially when the
+	rewrite claimed to fix bugs, but not a single regression test has been
+	added to the suite).
+
+** Commit Rules
+
+	Once you know you can commit a patch (because of the rules above) there
+	are a few other small rules to follow:
+	*) Always add a changelog entry with a meaningful explanation
+	*) If you fix a bug, add a regression test for it in the regression
+	suite
+	*) Don't commit unrelated changes together with a fix: do fine-grained
+	commits
+	*) Always check what you're committing: make sure you're only committing
+	what you need and make sure you don't change line endings and 
+	whitespace. Do a 'cvs diff -u' of the files you're going to commit and 
+	check the changes.
+	*) Don't do reformatting commits, unless you're the original author of
+	the code
+	*) When fixing bugs, don't follow the documentation blindly, it may 
+	well be wrong. Test the behavior on the MS runtime or ask on the list 
+	for discussion if unsure. Don't be afraid of having your changes
+	reviewed.
+	*) Never remove copyright notices from the code
+	*) Never remove licensing info from code
+	*) Never commit code you didn't write yourself or code that doesn't
+	have a suitable license
+	*) Follow the style conventions
+	*) Keep an eye on performance considerations, especially for code in
+	core classes, ask on the list for guidance
+	*) Do a regression test run and a bootstrapping build if making changes
+	to core functionality before committing. Do not commit code that would 
+	break the compile, because that wastes everybody's time.  Two things 
 	are important in this step: trying to build your sources and making 
 	sure that you add all the new files before you do a commit.
 
+	Also, remember to pat yourself on the back after the commit, smile and
+	think we're a step closer to a better free software world.
+
 
 * Using CVS.
 
@@ -66,14 +157,16 @@
 	ssh-keygen -t rsa
 </pre>
 
-	And mail me the id_rsa.pub file.
+	And mail <a href="mailto:miguel@ximian.com">miguel</a> the 
+	id_rsa.pub file.
 
 	If you are using SSH version 1, run:
 <pre>
 	ssh-keygen
 </pre>
 
-	And mail me your identity.pub file.
+	And mail <a href="mailto:miguel@ximian.com">miguel</a> your 
+	identity.pub file.
 
 	If you are using SSH from SSH Communications Security (they offer
 	a free SSH client for personal use), you have to use OpenSSH to
@@ -86,7 +179,8 @@
 	
 	where the file id_XXX.pub is your public key file, 
 	normally located under ~/.ssh/ or ~/.ssh2/.
-	Send to miguel the my_public_key.pub file. 
+	Send to <a href="mailto:miguel@ximian.com">miguel</a> the 
+	my_public_key.pub file. 
 
 	The *exact* format for this file must be:
 
@@ -128,7 +222,7 @@
 ** Making patches
 
 	Usually you will want to make a patch to contribute, and let
-	other people review it before commiting it.  To obtain such a
+	other people review it before committing it.  To obtain such a
 	"patch", you type:
 	
 <pre>
@@ -137,7 +231,25 @@
 	mail mono-list@ximian.com < file.diff
 </pre>
 
-** Keeping track of changes.
+** Committing your work
+
+	Once you get approval to commit to the CVS, or if you are
+	committing code that you are the maintainer of, you will want
+	to commit your code to CVS. 
+
+	To do this, you have to "add" any new files that you created:
+
+<pre>
+	cvs add new-file.cs
+</pre>
+
+	And then commit your changes to the repository:
+
+<pre>
+	cvs commit file-1.cs file-2.cs
+</pre>
+
+* Keeping track of changes.
 
 	We provide two e-mail based mechanisms to keep track of
 	changes to the code base:
@@ -156,28 +268,6 @@
 
 	We hope to offer LXR and Bonsai in the future as well.
 
-** Commiting your work
-
-	Once you get approval to commit to the CVS, or if you are
-	commiting code that you are the maintainer of, you will want
-	to commit your code to CVS. 
-
-	To do this, you have to "add" any new files that you created:
-
-<pre>
-	cvs add new-file.cs
-</pre>
-
-	And then commit your changes to the repository:
-
-<pre>
-	cvs commit file-1.cs file-2.cs
-</pre>
-
-* The Mailing Lists
-
-	To keep track of the various development and changes to the
-	CVS tree, you can subscribe to the mono-cvs-list@ximian.com.
 	To subscribe, send an email message to
 	mono-cvs-list-request@ximian.com and in the body of the
 	message put `subscribe'.
@@ -190,10 +280,3 @@
 	the <a
 	href="mailto:mono-patches-request@ximian.com">mono-patches@ximian.com</a>
 	to receive the patches as they are checked into CVS. 
-
-** Recommendations
-
-	To build the sources, most of the type trying the `make' command
-	is enough.  In some cases (the class libraries) we use nant, so
-	you need to run nant manually.
-