docs-xml/Samba-Developers-Guide/contributing.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3
   4 <chapter id="contributing">
   5 <chapterinfo>
   6         &author.jelmer;
   7 </chapterinfo>
   8
   9 <title>Contributing code</title>
  10
  11 <para>Here are a few tips and notes that might be useful if you are
  12         interested in modifying samba source code and getting it into
  13         samba's main branch.</para>
  14
  15 <variablelist>
  16         <varlistentry>
  17                 <term>Retrieving the source</term>
  18
  19                 <listitem>
  20                 <para>In order to contribute code to samba, make sure you have the
  21                         latest source. Retrieving the samba source code from CVS is
  22                         documented in the appendix of the Samba HOWTO Collection.
  23                 </para>
  24                 </listitem>
  25         </varlistentry>
  26
  27         <varlistentry>
  28                 <term>Discuss large modifications with team members</term>
  29                 <listitem>
  30                 <para>Please discuss large modifications you are going to make
  31                 with members of the samba team. Some parts of the samba code
  32                 have one or more 'owners' - samba developers who wrote most
  33                 of the code and maintain it.
  34                 </para>
  35
  36                 <para>This way you can avoid spending your time and effort on
  37                 something that is not going to make it into the main samba branch
  38                 because someone else was working on the same thing or because your
  39                 implementation is not the correct one.
  40                 </para>
  41                 </listitem>
  42         </varlistentry>
  43
  44         <varlistentry>
  45                 <term>Patch format</term>
  46                 <listitem>
  47                 <para>Patches to the samba tree should be in unified diff format,
  48                         e.g. files generated by <userinput>diff -u</userinput>.
  49                 </para>
  50
  51                 <para>If you are modifying a copy of samba you retrieved from CVS,
  52                 you can easily generate a diff file of these changes by running
  53                 <userinput>cvs diff -u</userinput>.</para>
  54                 </listitem>
  55         </varlistentry>
  56
  57         <varlistentry>
  58                 <term>Points of attention when modifying samba source code</term>
  59                 <listitem><para>
  60                 <itemizedlist>
  61                 <listitem><para>Don't simply copy code from other places and modify it until it
  62                 works. Code needs to be clean and logical. Duplicate
  63                 code is to be avoided.</para></listitem>
  64                 <listitem><para>Test your patch. It might take a while before one of us looks
  65                 at your patch so it will take longer before your patch when your patch
  66                 needs to go thru the review cycle again.</para></listitem>
  67                 <listitem><para>Don't put separate patches in one large diff file. This makes
  68                 it harder to read, understand and test the patch. You might
  69                 also risk not getting a good patch committed because you mixed it
  70                 with one that had issues. </para></listitem>
  71                 <listitem><para>Make sure your patch complies to the samba coding style as
  72                 suggested in the coding-suggestions chapter. </para></listitem>
  73                         </itemizedlist>
  74                 </para>
  75                 </listitem>
  76         </varlistentry>
  77
  78         <varlistentry>
  79                 <term>Sending in bugfixes</term>
  80                 <listitem>
  81                 <para>Bugfixes to bugs in samba should be submitted to samba's
  82                 <ulink url="https://bugzilla.samba.org/">bugzilla system</ulink>,
  83                 along with a description of the bug.
  84                 </para>
  85                 </listitem>
  86         </varlistentry>
  87
  88         <varlistentry>
  89                 <term>Sending in feature patches</term>
  90                 <listitem>
  91                 <para>Send feature patches along with a description of what the
  92                 patch is supposed to do to the
  93                 <ulink url="mailto:samba-technical@lists.samba.org">Samba-technical mailinglist</ulink> and possibly to a samba team member who is (one of the) 'owners'
  94                 of the code you made modifications to. We are all busy people
  95                 so everybody tends to 'let one of the others handle it'. If nobody
  96                 responded to your patch for a week, try to send it again until you
  97                 get a response from one of us.
  98                 </para></listitem>
  99         </varlistentry>
 100
 101         <varlistentry>
 102                 <term>Feedback on your patch</term>
 103                 <listitem>
 104                 <para>One of the team members will look at your patch and either
 105                 commit your patch or give comments why he won't apply it. In the
 106                 latter case you can fix your patch and re-send it until
 107                 your patch is approved.</para>
 108                 </listitem>
 109         </varlistentry>
 110 </variablelist>
 111
 112 </chapter>