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