doc/contributing

   1 * Contributing to the Mono project
   2
   3         Mono has not been completed yet.  It is a project under
   4         active development and with a vibrant community.  If you are
   5         looking at ways of helping the project, you have come to the
   6         right web page.
   7
   8         There are three different philosophical approaches to helping
   9         the Mono project, the selfish way, the altruistic or the
  10         educational way.
  11
  12         The <b>selfish</b> way is packed with adventure.  You start by
  13         building your own software, and start using the compiler and
  14         tools that come with Mono.  Eventually you will run into
  15         missing features, or a bug in the software.  Since we ship all
  16         the source code for Mono, you can start tracking down the
  17         problem.  Depending on how much time you have to devote to the
  18         problem you could: <a href="http://bugzilla.ximian.com">File a
  19         bug report</a>;  track down the problem and provide a better
  20         <a href="http://bugzilla.ximian.com">bug report</a>;  fix the
  21         bug and provide a patch (you can <a
  22         href="mailto:mono-list@ximian.com">post it</a> to the <a
  23         href="http://lists.ximian.com/mailman/listinfo/mono-list">mono
  24         mailing list</a>;  or discuss the solution on the mailing
  25         list.   Ideally you will also write a <a
  26         href="testing.html">regression test</a> so the bug does not
  27         get re-introduced in the future.
  28
  29         The <b>altruistic</b> is probably the easiest because you get
  30         to pick a piece of Mono that you might want to work on.  You
  31         can pick an unfinished <a href="class-library.html">class</a> (from our <a
  32         href="class-status.html">class status page</a>); help with the
  33         <a href="documentation.html">documentation effort</a> (<a
  34         href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mailing
  35         list for the documentation effort</a>); fix existing <a
  36         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
  37         bugs</a>; <a
  38         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
  39         bugs</a>; help with the <a href="tools.html">tools</a> or
  40         writing <a href="testing.html">tests</a> that help make Mono
  41         more robust or help with the <a
  42         href="http://www.go-mono.com/winforms.html">Winforms
  43         effort</a>.
  44
  45         The <b>educational</b> way is an interesting one, because you
  46         pick a technology you are interested in, and work on that
  47         technology to learn the technology.
  48
  49         Those are just broad things that need to be worked on, but
  50         something that would help tremendously would be to help with
  51         small duties in the project that need to be addressed.
  52
  53         You can see what needs to be done in the class libraries <a href="class-status.html">here</a>
  54
  55 * IRC Channel
  56
  57         Many developers get together on the <b>#mono</b> irc channel
  58         on the <b>irc.gnome.org</b> server.
  59
  60 ** To start contributing
  61
  62         As a programmer, you can contribute in three different scenarios to Mono:
  63
  64         <ul>
  65                 * If you only have Linux/Unix.
  66                 * If you only have Windows.
  67
  68                 * If you have both Linux and Windows.
  69         </ul>
  70
  71         You might also want to check our <a href="#setup">common
  72         setups</a> section that describes some common setups that people
  73         use while working on Mono.
  74
  75 *** Contributing to the class library, regression tests or the compiler
  76
  77         This only requires Windows currently.
  78
  79         To start developing classes or to contribute to the compiler,
  80         you only need Windows and the .NET Framework 1.0 SDK.  Please notice
  81         that you do not need Visual Studio (although you can use it if
  82         you want).  The .NET Framework SDK requires some version of
  83         Windows XP or Windows NT.  If you are running Windows 98, 95
  84         or Me, you could use instead the <a
  85         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
  86         lacks the documentation browser and the ildasm program (C#, VB, JScript and IL
  87         assembler are included).
  88
  89         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>
  90
  91         If you are new to .NET, writing regression tests is a good way
  92         of starting to contribute: it will help you get used to C# as
  93         well as getting comfortable with the .NET APIs.
  94
  95         This helps because at this point you might be the best
  96         qualified person to fix a problem found by the regression
  97         test, or you might have a new class to implement in the .NET
  98         world that only has a test suite.
  99
 100         To get started writing tests see the <a href="testing.html">Test Suite</a>
 101         section. <a href="mono-contribution-howto.html">Here</a> there is a good All-In-One introduction to the art of writing tests.
 102
 103
 104 *** Contributing to the runtime engine
 105
 106         This only requires Linux, currently some tasks are easier if you
 107         have access to Windows as well.
 108
 109         Here are a few things you can do:
 110         <ul>
 111                 * Port the runtime to other architectures.
 112                 * Port the runtime to other operating systems.
 113                 * Finish the IL code verifier in the runtime.
 114                 * Hack the JIT, improve the code generator, add new
 115                   pattern rules, improve the register allocator.
 116                 * Implement the debugging interfaaces
 117         </ul>
 118
 119 ** Bug reporting
 120
 121         If you find bugs in Mono, please make sure you enter a bug
 122         report so we can keep track of problems in Mono.
 123
 124         To enter bug reports go to <a href="http://bugzilla.ximian.com">
 125         http://bugzilla.ximian.com</a> and enter bug reports against
 126         your favorite component (Mono, Runtime, C# compiler).
 127
 128         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>
 129
 130 ** Small tasks
 131
 132         A few smaller tasks are here, dropped in no particular order:
 133         <ul>
 134                 * <b>Mono/doc and web site:</b> They need to be
 135                   packaged up in the official `distribution'
 136
 137                 * Adding serialization support to all the classes.
 138
 139                   We have many classes, but we have not implemented in
 140                   many cases the serialization and re-incarnation support in
 141                   them (this is pretty straight forward code, and simple,
 142                   but there is a lot to be done here).
 143         </ul>
 144
 145 * Emacs support
 146
 147         Brad Merryl's C# mode for Emacs is available: <a
 148         href="http://www.cybercom.net/~zbrad/DotNet/Emacs/">http://www.cybercom.net/~zbrad/DotNet/Emacs/</a>
 149
 150 * Books on C# and DotNet.
 151
 152         <ul>
 153         * Dotnet Books (<a href="http://www.dotnetbooks.com">http://www.dotnetbooks.com</a>)
 154
 155         * Dotnet Resources (<a href="http://www.dotnetexperts.com/resources/">
 156           http://www.dotnetexperts.com/resources</a>)
 157
 158         * O'Reilly C# Essentials (<a href="http://www.oreilly.com/catalog/csharpess/">
 159           http://www.oreally.com/catalog/csharpess</a>)
 160
 161         * O'Really .NET Essentials (<a href="http://www.oreilly.com/catalog/dotnetfrmess/">
 162           http://www.oreally.com/catalog/dotnetfrmess</a>)
 163         </ul>
 164
 165 <a name="setup">
 166 * Common Setups
 167
 168         People running both Linux and Windows while contributing to
 169         Mono use a number of tricks to increase their productivity.
 170
 171         Scenarios:
 172
 173         <ul>
 174                 * <b>Linux host and Windows host</b>
 175
 176                   The Windows file system is shared (right click on
 177                   your hard drive icon, and select sharing, allow this
 178                   to be shared).
 179
 180                   The Windows machine has the required build tools
 181                   (cygwin, and the .NET framework).  On the Windows
 182                   machine, you want to setup the ssh server (run the
 183                   ssh-host-config program to configure your ssh) and
 184                   run it (from a cygwin terminal, type: /usr/sbin/sshd).
 185
 186                   From the Linux side, you want to mount the Windows
 187                   file system, using something like this:
 188
 189 <tt><pre>
 190         mount -t smbfs -o uid=miguel,username="Miguel de Icaza" "//quack/c$" /mnt
 191 </pre></tt>
 192
 193                   In the above example, my Linux user name is
 194                   `miguel', and this will allow this user to have
 195                   read/write access to the share.
 196
 197                   The host name is `quack', and the name of the share
 198                   is `c$' (that is the C: partition).
 199
 200                   The file system is accessible on /mnt.
 201
 202                   You can perform your cvs update and cvs commits from
 203                   the /mnt directory, and run Emacs or your favorite
 204                   Linux text editor on the Unix side in this way.
 205
 206                   Then from another terminal, you can ssh into your
 207                   Windows box using ssh, like this: ssh "Miguel de Icaza@quack"
 208         </ul>
 209
 210 * Special Note
 211
 212         If you have looked at Microsoft's implementation of .NET or
 213         their shared source code, you may not be able to contribute
 214         to Mono.  Details will follow when we know more about this.
 215
 216         In general be careful when you are implementing free software
 217         and you have access to proprietary code.  We need to make sure
 218         that we are not using someone else's copyrighted code
 219         accidentally.
 220
 221         Please do not use the <b>ildasm</b> program to disassemble
 222         proprietary code when you are planning to reimplement a class
 223         for Mono.  If you have done this, we might not be able to use
 224         your code.
 225
 226         Please stick to published documentation for implementing any
 227         classes.