* CVS Access
- If you are an active Mono developer, you can get a CVS account
- that hosts the Mono source code.
+ Here we describe how one obtains commit access to the CVS repository
+ and the responsibilities that come with that access privilege.
- Send an e-mail to miguel with your public SSH key for this purpose.
+** 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 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 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 mono-hackers-list@ximian.com.
+
+** 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:
+ <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
+ <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.
+
+
+* 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:miguel@ximian.com">miguel</a> the
+ id_rsa.pub file.
+
+ If you are using SSH version 1, run:
+<pre>
+ ssh-keygen
+</pre>
+
+ 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
+ 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:miguel@ximian.com">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.org">http://www.cygwin.org</a>)
+ href="http://www.cygwin.com">http://www.cygwin.com</a>)
Unix users will probably have those tools installed already.
updated sources, use:
<pre>
- cvs -z3 update mcs mono
+ 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 commiting it. To obtain such a
+ other people review it before committing it. To obtain such a
"patch", you type:
<pre>
mail mono-list@ximian.com < file.diff
</pre>
-** Commiting your work
+** Committing 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
+ 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.c
+ cvs add new-file.cs
</pre>
And then commit your changes to the repository:
<pre>
- cvs commit .
+ cvs commit file-1.cs file-2.cs
</pre>
-** The Mailing List
+* Keeping track of changes.
+
+ We provide two e-mail based mechanisms to keep track of
+ changes to the code base:
+
+ <ul>
+ * <a href="mailto:mono-patches-request@ximian.com">
+ mono-patches@ximian.com</a>: This mailing list receives
+ in patch form all the changes that are being made to the
+ CVS.
+
+ * <a href="mailto:mono-cvs-list-request@ximian.com">
+ mono-cvs-list@ximian.com</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 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'.
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.
-
-** Recommendations
-
- Please do not commit code that would break the compile to the
- CVS, because that normally wastes everybody's time.
-
- Make sure that you add all the files before you do a commit.
-
- 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.
+ You might also want to track the live changes, subscribe to
+ the <a
+ href="mailto:mono-patches-request@ximian.com">mono-patches@ximian.com</a>
+ to receive the patches as they are checked into CVS.