summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/writing.docbook57
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/writing.docbook b/doc/writing.docbook
index f33b293..70e09d9 100644
--- a/doc/writing.docbook
+++ b/doc/writing.docbook
@@ -19,6 +19,63 @@ the files to patch, what kind of patchset it is, and whether to fail
or not if the patching is not completed as intended.
</para>
+<para>
+To facilitate writing new patchsets, the names of the functions that
+are defined into the patchset's script are standardised, so that the
+parameters they get and the result they echo out can be relied upon
+and used by autoepatch safely.
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>patch_targets</term>
+ <listitem>
+
+ <para>
+ This function is the basis to start writing a new patchset, it is
+ used to identify where the patches are gonna be applied. The
+ results are simply returned on the standard output, one per
+ line. This function is supposed to check if the patch should or
+ should not be applied over a file or a directory, by grepping, if
+ needed, for key phrases that would show if the patch is needed or
+ not.
+ </para>
+
+ <para>
+ This function is not supposed to check for the applicability of
+ the patch on the current system. The reason for this is that it's
+ way simpler to test all patchsets every time, so that if errors
+ are added to the patchset, they can be fixed immediately.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>patch_required</term>
+ <listitem>
+
+ <para>
+ This function is called in the case the patchset failed to apply
+ entirely; it is supposed to return 0 (truth value) if the patch is
+ important, and autoepatch has to fail if it's not applied (and
+ thus stop the merge process), or 1 (untruth value) if the patch is
+ optional and/or it's not of first important for the current setup.
+ </para>
+
+ <para>
+ The reason to have this function is that some patches might be only
+ needed on some targets (for instance Gentoo/FreeBSD, or uClibc or
+ Darwin systems), or only in some situations (newer autotools,
+ newer glibc or linux-headers), and for the rest of the cases, it's
+ just an assurance and a testing purpose to apply the patch on
+ every use. So the failure on autoepatch, when a patchset fails to
+ apply, is entirely decided by the value returned by this function.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
</sect1>
</chapter>