From a51de094aba9e272e6f216a705fc9259553dc9cc Mon Sep 17 00:00:00 2001
From: Darren Salt <linux@youmustbejoking.demon.co.uk>
Date: Sun, 7 Mar 2010 18:39:55 +0000
Subject: Update docs wrt lack of CVS; retitle the FAQ list.

---
 doc/hackersguide/hackersguide.sgml |  3 +-
 doc/hackersguide/overview.sgml     | 67 ++++++++++++++++++++++++++++++--------
 2 files changed, 55 insertions(+), 15 deletions(-)

(limited to 'doc/hackersguide')

diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml
index ebc42d4c7..e33304110 100644
--- a/doc/hackersguide/hackersguide.sgml
+++ b/doc/hackersguide/hackersguide.sgml
@@ -22,9 +22,10 @@
    <author><firstname>Marco</firstname><surname>Z&uuml;hlke</surname></author>
    <author><firstname>Mike</firstname><surname>Melanson</surname></author>
    <author><firstname>Michael</firstname><surname>Roitzsch</surname></author>
+   <author><firstname>Darren</firstname><surname>Salt</surname></author>
   </authorgroup>
   <copyright>
-   <year>2001-2003</year>
+   <year>2001-2010</year>
    <holder>the xine project team</holder>
   </copyright>
   <abstract>
diff --git a/doc/hackersguide/overview.sgml b/doc/hackersguide/overview.sgml
index 18cc40396..bf036edbc 100644
--- a/doc/hackersguide/overview.sgml
+++ b/doc/hackersguide/overview.sgml
@@ -793,7 +793,7 @@
   </sect2>
  </sect1>
 
- <sect1>
+ <sect1 id="contribute">
   <title>How to contribute</title>
   <para>
    Make sure you send your patches in unified diff format to
@@ -811,21 +811,60 @@
    committable. This normally means that we want your name and email address
    (we're not keen on pseudonyms), a subject line which provides a
    convenient summary of your changes, and body text which provides a longer
-   description (if needed). Patches must be generated using <command>hg
-   diff</command> or <command>cvs -z9 diff</command>, depending on which is
-   used for the repository, and always from within the top level of the
-   checked-out source.
+   description (if needed).
+  </para>
+  <para>
+   There are a few ways to submit your patches:
   </para>
+  <itemizedlist>
+   <listitem>
+    <para>
+     <command>hg diff</command> is probably the easiest. You'll need a
+     subject line and body text as described above. If you're copying or
+     renaming files, or a file should be marked as executable, then use
+     <command>hg diff --git</command>; this will include the necessary
+     information (if copying or renaming, you need to have used <command>hg
+     copy</command> or <command>hg rename</command> for this to work).
+    </para>
+    <para>
+     If you're attaching the patch (recommended), then including the
+     metadata in the patch file is recommended, e.g.
+    </para>
+    <screen>From: Fred Patcher &lt;patcher@example.com&gt;
+Subject: Properly toggle the randomiser switch
+
+The randomiser switch was sometimes not being toggled, leading to random
+behaviour.
+
+diff --git a/foo/control.c b/foo/control.c
+...</screen>
+   </listitem>
+   <listitem>
+    <para>
+     <command>diff -u</command> is also acceptable, but we prefer that you
+     do so from the top-level directory within the source code (prefix the
+     files' path names with <parameter>./</parameter>) or from the directory
+     containing the source code directory. Basically, use <command>hg
+     diff</command> if you can.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     <command>hg email</command> is preferred. You'll need to commit your
+     changes locally for this to work, but this is the easiest way of
+     sending a set of patches for inclusion and review; it'll send the mail
+     directly.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     <command>hg export</command> can also be used with specific changeset
+     identifiers. Again, you'll need to commit your changes locally for
+     this to work.
+    </para>
+   </listitem>
+  </itemizedlist>
   <para>
-   If your patch is intended for a Mercurial-format repository, then
-   committing it locally and using
-   <command>hg export <parameter>.</parameter> &gt;<filename>foo.patch</filename></command>
-   to create the file to be attached is acceptable (but note that the first
-   line &ndash; up to the first line feed &ndash; of the commit message is regarded as
-   the patch summary; if you're not sure, check with
-   <command>hg log -r<parameter>.</parameter></command>.
-   Alternatively, use <token>From:</token> and <token>Subject:</token> lines
-   in the patch file itself; this is useful when forwarding.
   </para>
   <para>
    Patches should normally be included as attachments. Some mail clients and
-- 
cgit v1.2.3