3 Here we describe how one obtains commit access to the CVS repository
4 and the responsibilities that come with that access privilege.
8 Briefly, CVS is a system tool used to store and maintain files and
9 a history of their changes over time. The Mono source code and related
10 files are kept on a CVS server at Ximian.
14 We mean "commit" access. This is the privilege to make permanent
15 changes to the Mono source code and related files. You need an account
16 created by the CVS server administrator in order to commit changes to
17 the files on that server.
19 ** How Does One Obtain Access?
21 Any active Mono developer can get a CVS account. Normally one is
22 considered an 'active' developer after sending several patches to the
23 mailing lists and/or bugzilla for review.
25 If you are not a developer, but want to access the latest sources,
26 please see the <a href="anoncvs.html">AnonCVS</a> instructions.
28 If you feel you are ready for a CVS account send an e-mail to
29 <a href="mailto:miguel@ximian.com">miguel</a> with your public OpenSSH
30 key for this purpose. Please specify if the key was generated with SSH
31 version 1 or version 2. Detailed instructions are below.
35 It is necessary that everyone with CVS commit access respect and
36 adhere to the following rules. If you ask for and are granted CVS
37 access, you are agreeing to follow these policies.
41 If you are about to commit code to a module, the code that is
42 being committed should be released under the same license as
43 the code that the module has.
45 Check the license if you are unsure, but it is basically:
46 class libraries X11; compiler and tools: GPL; runtime: LGPL.
48 If in doubt, check with the maintainers of the module, or send
49 mail to mono-hackers-list@ximian.com.
53 Even if you have CVS commit access, that doesn't mean you can change
54 code at will in any directory or module. Directories and Namespaces
55 have a sort of unofficial ownership. If you are not the owner of a
56 piece of code and you want to make changes/fixes to it, there are two
58 1) The change is a typo fix or a one-liner build or trivial fix. In
59 this case almost anyone can commit (always remembering to add the
60 proper changelog entry to explain the change). We say "almost anyone",
61 because changes to certain directories almost always should be reviewed
62 first. Such as changes to core stuff: corlib/System, System.Collections,
63 mini/, metadata/, System.IO.
65 2) The change is larger. In this case the patch *must* be sent to
66 mono-devel-list for review by the owner of the code and by the other
67 hackers. Always submit such patches to the list or bugzilla, although
68 you may put the owner of the code in the CC header. Hackers come and go.
69 Mailing a patch to only a personal address is a good way to get the
70 patch forgotten and missed. Plus, getting the patches reviewed as well
71 as reviewing them, is a good thing, so try to get used to it.
73 Note: If the patch is an addition of code and doesn't change any of the
74 existing code, the rules are slightly relaxed: there is more freedom
75 in committing such changes, if they don't interfere with the existing
80 Now, how do you get to be the owner of a chunk of code? The answer is
81 simple. You wrote the code, so you're the unofficial owner. There is
82 also another way. After sending a few patches for the code, the
83 owner (or the core developers of mono, if the owner somehow disappeared)
84 trusts you and tells you you're free to commit without getting his
88 Here is a (partial) list of namespaces/directories with their owners:
90 <li>Debugger module and debug code in mono: martin
91 <li>mcs compiler: miguel, martin, ravi
92 <li>Reflection/Reflection.Emit: lupus, zoltan
94 <li>mini: lupus, dietmar
95 <li>test suite: nickd (though anyone should feel free to add test cases)
96 <li>System.IO: dick, ville
97 <li>security stuff: spouliot
99 <li>System.Web and related: gonzalo
100 <li>System.Xml: eno, piers
101 <li>Remoting: dietmar, lluis
102 <li>interop/marshal: dietmar
106 If you are the owner of a piece of code, feel free to commit code, and
107 delegate the work to others.
109 But, if you're not the owner of the code, committing a rewrite without
110 getting a review first is not good cvsitizenship (especially when the
111 rewrite claimed to fix bugs, but not a single regression test has been
116 Once you know you can commit a patch (because of the rules above) there
117 are a few other small rules to follow:
119 <li>Always add a changelog entry with a meaningful explanation
120 <li>If you fix a bug, add a regression test for it in the regression
122 <li>Don't commit unrelated changes together with a fix: do fine-grained
124 <li>Always check what you're committing: make sure you're only committing
125 what you need and make sure you don't change line endings and
126 whitespace. Do a 'cvs diff -u' of the files you're going to commit and
128 <li>Don't do reformatting commits, unless you're the original author of
130 <li>When fixing bugs, don't follow the documentation blindly, it may
131 well be wrong. Test the behavior on the MS runtime or ask on the list
132 for discussion if unsure. Don't be afraid of having your changes
134 <li>Never remove copyright notices from the code
135 <li>Never remove licensing info from code
136 <li>Never commit code you didn't write yourself or code that doesn't
137 have a suitable license
138 <li>Follow the style conventions
139 <li>Keep an eye on performance considerations, especially for code in
140 core classes, ask on the list for guidance
141 <li>Do a regression test run and a bootstrapping build if making changes
142 to core functionality before committing. Do not commit code that would
143 break the compile, because that wastes everybody's time. Two things
144 are important in this step: trying to build your sources and making
145 sure that you add all the new files before you do a commit.
148 Also, remember to pat yourself on the back after the commit, smile and
149 think we're a step closer to a better free software world.
154 This is a small tutorial for using CVS.
156 ** Generating an SSH key
158 If you are using SSH version 2, please generate your key using:
164 And mail <a href="mailto:miguel@ximian.com">miguel</a> the
167 If you are using SSH version 1, run:
172 And mail <a href="mailto:miguel@ximian.com">miguel</a> your
175 If you are using SSH from SSH Communications Security (they offer
176 a free SSH client for personal use), you have to use OpenSSH to
177 convert your public key to the required format. You have to use
178 OpenSSH's ssh-keygen program and write the following:
181 ssh-keygen -i -f id_XXX.pub > my_public_key.pub
184 where the file id_XXX.pub is your public key file,
185 normally located under ~/.ssh/ or ~/.ssh2/.
186 Send to <a href="mailto:miguel@ximian.com">miguel</a> the
187 my_public_key.pub file.
189 The *exact* format for this file must be:
195 You will need CVS and SSH. Windows users can get both by
196 installing Cygwin (<a
197 href="http://www.cygwin.com">http://www.cygwin.com</a>)
199 Unix users will probably have those tools installed already.
201 ** Checking out the sources
203 To check out the sources for the first time from the
204 repository, use this command:
208 export CVSROOT=username@mono-cvs.ximian.com:/cvs/public
212 ** Updating your sources
214 Every day people will be making changes, to get your latest
215 updated sources, use:
218 cvs -z3 update -Pd mcs mono
221 Note: The '-z3' enables compression for the whole cvs action.
222 The '-Pd' makes the update operation (P)rune directories that
223 have been deleted and get new (d)irectories added to the
228 Usually you will want to make a patch to contribute, and let
229 other people review it before committing it. To obtain such a
233 cd directory-you-want-to-diff
234 cvs -z3 diff -u > file.diff
235 mail mono-list@ximian.com < file.diff
238 ** Committing your work
240 Once you get approval to commit to the CVS, or if you are
241 committing code that you are the maintainer of, you will want
242 to commit your code to CVS.
244 To do this, you have to "add" any new files that you created:
250 And then commit your changes to the repository:
253 cvs commit file-1.cs file-2.cs
256 * Keeping track of changes.
258 We provide two e-mail based mechanisms to keep track of
259 changes to the code base:
262 * <a href="mailto:mono-patches-request@ximian.com">
263 mono-patches@ximian.com</a>: This mailing list receives
264 in patch form all the changes that are being made to the
267 * <a href="mailto:mono-cvs-list-request@ximian.com">
268 mono-cvs-list@ximian.com</a>: This mailing list only
269 receives the CVS commit logs with a list of files
273 We hope to offer LXR and Bonsai in the future as well.
275 To subscribe, send an email message to
276 mono-cvs-list-request@ximian.com and in the body of the
277 message put `subscribe'.
279 This will send you an email message every time a change is
280 made to the CVS repository, together with the information that
281 the author of the changes submitted.
283 You might also want to track the live changes, subscribe to
285 href="mailto:mono-patches-request@ximian.com">mono-patches@ximian.com</a>
286 to receive the patches as they are checked into CVS.