| 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@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>
|
|---|
