Fix the ChangeLog.

[mono/afaerber.git] / web / contributing

* Contributing to the Mono project

        Mono has not been completed yet.  It is a project under
        active development and with a vibrant community.  If you are
        looking at ways of helping the project, you have come to the
        right web page. 

        There are three different philosophical approaches to helping
        the Mono project, the selfish way, the altruistic or the
        educational way.

        The <b>selfish</b> way is packed with adventure.  You start by
        building your own software, and start using the compiler and
        tools that come with Mono.  Eventually you will run into
        missing features, or a bug in the software.  Since we ship all
        the source code for Mono, you can start tracking down the
        problem.  Depending on how much time you have to devote to the
        problem you could: <a href="http://bugzilla.ximian.com">File a
        bug report</a> (read <a href="#goodbugreport">this</a>); track
        down the problem and provide a better
        <a href="http://bugzilla.ximian.com">bug report</a>;  fix the
        bug and provide a patch (you can <a
        href="mailto:mono-list@ximian.com">post it</a> to the <a
        href="http://lists.ximian.com/mailman/listinfo/mono-list">mono
        mailing list</a>;  or discuss the solution on the mailing
        list.   Ideally you will also write a <a
        href="testing.html">regression test</a> so the bug does not
        get re-introduced in the future. 

        The <b>altruistic</b> is probably the easiest because you get
        to pick a piece of Mono that you might want to work on.  You
        can pick an unfinished <a href="class-library.html">class</a> (from our <a
        href="class-status.html">class status page</a>); help with the
        <a href="documentation.html">documentation effort</a> (<a
        href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mailing
        list for the documentation effort</a>); fix existing <a
        href=http://bugzilla.ximian.com/buglist.cgi?product=Mono%2FClass+Libraries&product=Mono%2FRuntime&component=CORLIB&component=misc&component=System&component=System.Web&component=System.XML&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&bug_file_loc=&bug_file_loc_type=substring&keywords=&keywords_type=anywords&op_sys_details=&op_sys_details_type=substring&version_details=&version_details_type=substring&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time&form_name=query">runtime
        bugs</a>; <a
        href="http://bugzilla.ximian.com/buglist.cgi?product=Mono%2FMCS&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&bug_file_loc=&bug_file_loc_type=substring&keywords=&keywords_type=anywords&op_sys_details=&op_sys_details_type=substring&version_details=&version_details_type=substring&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time&form_name=query">compiler
        bugs</a>; help with the <a href="tools.html">tools</a> or
        writing <a href="testing.html">tests</a> that help make Mono
        more robust or help with the <a
        href="http://www.go-mono.com/winforms.html">Winforms
        effort</a>.

        The <b>educational</b> way is an interesting one, because you
        pick a technology you are interested in, and work on that
        technology to learn the technology.  

        Those are just broad things that need to be worked on, but
        something that would help tremendously would be to help with
        small duties in the project that need to be addressed. 

        You can see what needs to be done in the class libraries <a href="class-status.html">here</a>

* IRC Channel

        Many developers get together on the <b>#mono</b> irc channel
        on the <b>irc.gnome.org</b> server.  

** To start contributing

        As a programmer, you can contribute in three different scenarios to Mono:

        <ul>
                * If you only have Linux/Unix.
                * If you only have Windows.

                * If you have both Linux and Windows.
        </ul>

        You might also want to check our <a href="#setup">common
        setups</a> section that describes some common setups that people
        use while working on Mono.

*** Contributing to the class library, regression tests or the compiler

        This only requires Windows currently.

        To start developing classes or to contribute to the compiler,
        you only need Windows and the .NET Framework 1.0 SDK.  Please notice
        that you do not need Visual Studio (although you can use it if
        you want).  The .NET Framework SDK requires some version of
        Windows XP or Windows NT.  If you are running Windows 98, 95
        or Me, you could use instead the <a
        href="http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/829/msdncompositedoc.xml">.NET Redist package</a>, but it
        lacks the documentation browser and the ildasm program (C#, VB, JScript and IL 
        assembler are included).

        You can get it <a href="http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/000/976/msdncompositedoc.xml&frame=true">here</a>

        If you are new to .NET, writing regression tests is a good way
        of starting to contribute: it will help you get used to C# as
        well as getting comfortable with the .NET APIs.  

        This helps because at this point you might be the best
        qualified person to fix a problem found by the regression
        test, or you might have a new class to implement in the .NET
        world that only has a test suite.  
        
        To get started writing tests see the <a href="testing.html">Test Suite</a>
        section. <a href="mono-contribution-howto.html">Here</a> there is a good All-In-One introduction to the art of writing tests.


*** Contributing to the runtime engine

        This only requires Linux, currently some tasks are easier if you
        have access to Windows as well.

        Here are a few things you can do:
        <ul>
                * Port the runtime to other architectures.
                * Port the runtime to other operating systems.
                * Finish the IL code verifier in the runtime.
                * Hack the JIT, improve the code generator, add new
                  pattern rules, improve the register allocator.
                * Implement the debugging interfaaces
        </ul>

** Bug reporting

        If you find bugs in Mono, please make sure you enter a bug
        report so we can keep track of problems in Mono.

        To enter bug reports go to <a href="http://bugzilla.ximian.com">
        http://bugzilla.ximian.com</a> and enter bug reports against
        your favorite component (Mono, Runtime, C# compiler).

        You can review the list of current bugs by going <a href="http://bugzilla.ximian.com/buglist.cgi?product=Mono%2FClass+Libraries&product=Mono%2FMCS&product=Mono%2FRuntime&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&bug_file_loc=&bug_file_loc_type=substring&keywords=&keywords_type=anywords&op_sys_details=&op_sys_details_type=substring&version_details=&version_details_type=substring&cmdtype=doit&order=%27Importance%27&form_name=query">here</a>

        Check our <a href="bugs.html">Bugs</a> that contains links to
        easily add a bug report, or to query the existing bugs.

<a name="goodbugreport"/>
** How to make good bug reports

        A mail from Paolo to mono-devel-list contained this check list:
        <ol>
                * Submit a test case, the smaller it is, the better

                * Use <a href="http://bugzilla.ximian.com">
                http://bugzilla.ximian.com</a> to report the bug.
                
                <p>In <b>addition</b> to bugzilla, posting to the list is
                fine if the bug merits larger exposure or design
                discussions to solve; posting to the list twice or more
                is just a way to annoy people and make them waste time,
                specially when you start a new thread about it.

                * If the test involves libraries or assemblies that are
                not part of mono, add info about where to download all
                the dependencies, and how to compile/install them.

                * If compiling the test case requires more than:
                <pre> mcs test.cs </pre>
                provide the <b>full command line</b> you used to compile
                the test.

                * If running the test requires more than:
                <pre> mono test.exe </pre>
                provide the <b>full command line</b> needed to replicate
                the bug.

                * Provide info about the version of the software you're
                using (both mono and the operating system or relevant
                libraries).

                * Provide the output you expect the test case to produce.
                
                * Provide the actual output <b>you</b> get from the test case.
        </ol>

        A good bug report complies with at least 6 items from the list.
        If your bug report complies with 3 or less items, it is very
        poor and it means it will take much more time to fix (when it's
        not ignored).

** Small tasks

        A few smaller tasks are here, dropped in no particular order:
        <ul>
                * <b>Mono/doc and web site:</b> They need to be
                  packaged up in the official `distribution'

                * Adding serialization support to all the classes.

                  We have many classes, but we have not implemented in
                  many cases the serialization and re-incarnation support in 
                  them (this is pretty straight forward code, and simple,
                  but there is a lot to be done here).
        </ul>

* Emacs support

        Brad Merryl's C# mode for Emacs is available: <a
        href="http://www.cybercom.net/~zbrad/DotNet/Emacs/">http://www.cybercom.net/~zbrad/DotNet/Emacs/</a>

* Books on C# and DotNet.

        <ul>
        * Dotnet Books (<a href="http://www.dotnetbooks.com">http://www.dotnetbooks.com</a>)

        * Dotnet Resources (<a href="http://www.dotnetexperts.com/resources/">
          http://www.dotnetexperts.com/resources</a>)

        * O'Reilly C# Essentials (<a href="http://www.oreilly.com/catalog/csharpess/">
          http://www.oreally.com/catalog/csharpess</a>)

        * O'Really .NET Essentials (<a href="http://www.oreilly.com/catalog/dotnetfrmess/">
          http://www.oreally.com/catalog/dotnetfrmess</a>)
        </ul>

<a name="setup">
* Common Setups

        People running both Linux and Windows while contributing to
        Mono use a number of tricks to increase their productivity.

        Scenarios:

        <ul>
                * <b>Linux host and Windows host</b>

                  The Windows file system is shared (right click on
                  your hard drive icon, and select sharing, allow this
                  to be shared).  

                  The Windows machine has the required build tools
                  (cygwin, and the .NET framework).  On the Windows
                  machine, you want to setup the ssh server (run the
                  ssh-host-config program to configure your ssh) and
                  run it (from a cygwin terminal, type: /usr/sbin/sshd).

                  From the Linux side, you want to mount the Windows
                  file system, using something like this:

<tt><pre>
        mount -t smbfs -o uid=miguel,username="Miguel de Icaza" "//quack/c$" /mnt
</pre></tt>

                  In the above example, my Linux user name is
                  `miguel', and this will allow this user to have
                  read/write access to the share.  

                  The host name is `quack', and the name of the share
                  is `c$' (that is the C: partition).  

                  The file system is accessible on /mnt.

                  You can perform your cvs update and cvs commits from
                  the /mnt directory, and run Emacs or your favorite
                  Linux text editor on the Unix side in this way.

                  Then from another terminal, you can ssh into your
                  Windows box using ssh, like this: ssh "Miguel de Icaza@quack"
        </ul>

* Special Note

        If you have looked at Microsoft's implementation of .NET or
        their shared source code, you may not be able to contribute
        to Mono.  Details will follow when we know more about this.

        In general be careful when you are implementing free software
        and you have access to proprietary code.  We need to make sure
        that we are not using someone else's copyrighted code
        accidentally. 

        Please do not use the <b>ildasm</b> program to disassemble
        proprietary code when you are planning to reimplement a class
        for Mono.  If you have done this, we might not be able to use
        your code.

        Please stick to published documentation for implementing any
        classes.