[mono.git] / web / ccvs

* CVS Access

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

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

        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.

        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>

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