mono/web/ccvs

* CVS Access

	Here we describe how one obtains commit access to the Mono CVS
	repository and the responsibilities that come with that access
	privilege.

	These only apply to the Mono CVS repository, and not to the <a
	href="http://forge.novell.com/modules/xfmod/community/?monocomm">Mono
	Community</a> repositories at Novell Forge.

** What is CVS?

	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.

** 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.

	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 are not a direct contributor to Mono,
	but want to host your .NET or Mono-based project, you can use
	<a href="forge.html">Novell Forge</a>.


	If you feel you are ready for a CVS account send an e-mail to
	<a href="mailto:[email protected]">miguel</a> with your public OpenSSH 
	key for this purpose.  We only support SSH2 at this point.

* 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 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:
	class libraries X11; compiler and tools: GPL; runtime: LGPL.

	If in doubt, check with the maintainers of the module, or send
	mail to [email protected].

** 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.

	<ul>
	<li> 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.

	<li> 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.
	</ul>

	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:
	<ul>
        <li>Debugger module and debug code in mono: martin
        <li>mcs compiler: miguel, martin, ravi
        <li>Reflection/Reflection.Emit: lupus, zoltan
        <li>IO-layer: dick
        <li>mini: lupus, dietmar
        <li>test suite: nickd (though anyone should feel free to add test cases)
        <li>System.IO: dick, ville
        <li>security stuff: spouliot
        <li>ilasm: jackson
        <li>System.Web and related: gonzalo
        <li>System.Xml: eno, piers
        <li>Remoting: dietmar, lluis
        <li>interop/marshal: dietmar
        <li>threads: dick
	</ul>

	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:

	<ul>
	<li>Always add a ChangeLog entry with a meaningful
	explanation, this file should be located in the same directory
	as the change you make.

	<li>The ChangeLog entry <b>must</b> be pasted on the CVS
	commit log, so the CVS commit log can be used to map to the
	changes as well.

	<li>The ChangeLog and the files that comprise related changes
	should be committed together, not one by one, otherwise the
	history is pretty much useless if related changes are
	separated during the commit.

	<li>If you fix a bug, add a regression test for it in the regression
	suite.

	<li>Don't commit unrelated changes together with a fix: do fine-grained
	commits.

	<li>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.

	<li>Don't do reformatting commits, unless you're the original author of
	the code.

	<li>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.

	<li>Never remove copyright notices from the code.

	<li>Never remove licensing info from code.

	<li>Never commit code you didn't write yourself or code that doesn't
	have a suitable license.

	<li>Follow the style conventions.

	<li>Keep an eye on performance considerations, especially for code in
	core classes, ask on the list for guidance.

	<li>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.

	</ul>

	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.

* Branches

	We have branched the CVS modules `mono', `mcs' and
	`libgdiplus', the tag to fetch these branches is: `mono-1-0',
	so you use the following command to fetch the mono-1-0
	branches:

<pre>
	cvs co -r mono-1-0 mono 
	cvs co -r mono-1-0 mcs
	cvs co -r mono-1-0 libgdiplus
</pre>

	I personally use a directory called `mono-1-0' to keep these
	together and a separate directory keeps my HEAD development,
	and I configure each one to different prefixes, so I can test
	and run code with HEAD or mono-1-0.

*** mono-1-0 policy

	This branch will only get bug fixes to critical and major errors.
	You must still get approval from the maintainer of the code to
	check-in code into this branch.

	Before submitting a patch for this branch, you should run all
	appropriate regression tests.  Upcoming mono-1.0.x versions
	will be produced from this branch.

*** mono HEAD policy

	HEAD should continue to build at all times: HEAD is not a
	dumping ground for partial work: you still must ensure that
	the build is not broken, and that no regressions are caused.
	Unlike the main branch, you do not need approval to minor
	changes, the same old rules apply.

	But for any large architectural change, you must check with
	the maintainers and get approval for the patches.  For these
	large changes, if you are touching someone else's code, you
	should contact the maintainer of that code and get approval
	from them.

	You must assume that HEAD will be packaged and distributed at
	any point, this will be the branch that we use for making the
	mono-1.1.x releases that will lead to our stable mono-1.2.x
	release.

	So, the bottom line is: do not check-in known regressions that
	break the build.  A lot of work is underway, and we must
	ensure the tree works.


* Using CVS.

	This is a small tutorial for using CVS.

** Generating an SSH key

	If you are using SSH version 2, please generate your key using:

<pre>
	ssh-keygen -t rsa
</pre>

	And mail <a href="mailto:[email protected]">miguel</a> the 
	id_rsa.pub file.

	If you are using SSH version 1, run:
<pre>
	ssh-keygen
</pre>

	And mail <a href="mailto:[email protected]">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
	convert your public key to the required format. You have to use 
	OpenSSH's ssh-keygen program and write the following:

<pre>
	ssh-keygen -i -f id_XXX.pub > my_public_key.pub
</pre>
	
	where the file id_XXX.pub is your public key file, 
	normally located under ~/.ssh/ or ~/.ssh2/.
	Send to <a href="mailto:[email protected]">miguel</a> the 
	my_public_key.pub file. 

	The *exact* format for this file must be:

<pre>
	ssh-rsa XXXXX....
</pre>

	You will need CVS and SSH.  Windows users can get both by
	installing Cygwin (<a
	href="http://www.cygwin.com">http://www.cygwin.com</a>)

	Unix users will probably have those tools installed already.

** Checking out the sources

	To check out the sources for the first time from the
	repository, use this command:

<pre>
	export CVS_RSH=ssh
	export [email protected]:/cvs/public
	cvs -z3 co mcs mono
</pre>

** Updating your sources

	Every day people will be making changes, to get your latest
	updated sources, use:

<pre>
	cvs -z3 update -Pd mcs mono
</pre>

	Note: The '-z3' enables compression for the whole cvs action.
	The '-Pd' makes the update operation (P)rune directories that
	have been deleted and get new (d)irectories added to the
	repository.

** Making patches

	Usually you will want to make a patch to contribute, and let
	other people review it before committing it.  To obtain such a
	"patch", you type:
	
<pre>
	cd directory-you-want-to-diff
	cvs -z3 diff -u > file.diff
	mail [email protected] < file.diff
</pre>

** 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>

* Using SVN
	
	This is a small tutorial for using SVN (subversion).
	For a more complete tutorial on subversion, look at
	<a href="http://svnbook.red-bean.com/">the svn book</a>
	or <a href="http://subversion.tigris.org">the svn homepage</a>

** Generating a key

	Follow the cvs instructions above.

** Checking out the sources

	To checkout the sources for the first time use the command:

	Note: You should be running 0.35.1 (latest) of svn before attempting
	anything here.

<pre>
	svn co svn+ssh://mono-cvs.ximian.com/svn/monodevelop/trunk/MonoDevelop
</pre>
	
	If you have a different username on mono-cvs and the local computer
	you can do the following:

<pre>
	svn co svn+ssh://[email protected]/svn/monodevelop/trunk/MonoDevelop
</pre>

	before checking out.

** Updating your sources

	You can update your repository to the latest copy of MonoDevelop by
	running the following command:

<pre>
	svn up
</pre>

	from inside your repository.

** Committing your work

	Before you commit anything, you should first update to the latest
	sources by following the updating directions. After you are up to date
	you need to run a:

<pre>
	svn add filename
</pre>

	for every file that you have created. You can get a list of these files
	by running:

<pre>
	svn status
</pre>

	After all the files are added, run:

<pre>
	svn commit
</pre>

	to commit your changes.

** For more information

	Look at the MonoDevelop website (coming soon)

* Keeping track of changes.

	We provide two e-mail based mechanisms to keep track of
	changes to the code base:
	
	<ul>
		* <a href="mailto:[email protected]">
		  [email protected]</a>: This mailing list receives
		  in patch form all the changes that are being made to the
		  CVS.

		* <a href="mailto:[email protected]">
		  [email protected]</a>: This mailing list only
		  receives the CVS commit logs with a list of files
		  modified.
	</ul>

	We hope to offer LXR and Bonsai in the future as well.

	To subscribe, send an email message to
	[email protected] and in the body of the
	message put `subscribe'.

	This will send you an email message every time a change is
	made to the CVS repository, together with the information that
	the author of the changes submitted.

	You might also want to track the live changes, subscribe to
	the <a
	href="mailto:[email protected]">[email protected]</a>
	to receive the patches as they are checked into CVS.