2010-04-16 Sebastien Pouliot <sebastien@ximian.com>

[mono/afaerber.git] / 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:miguel@ximian.com">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 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.

        <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: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.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 CVSROOT=username@mono-cvs.ximian.com:/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 mono-list@ximian.com < 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://username@mono-cvs.ximian.com/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: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 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.

        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.