|author||Diego Elio Pettenò <email@example.com>||2006-12-31 01:13:10 +0000|
|committer||Diego Elio Pettenò <firstname.lastname@example.org>||2006-12-31 01:13:10 +0000|
|parent||Start writing documentation on writing patchsets. (diff)|
Start documenting the functions in the patchset's script.
svn path=/trunk/; revision=32
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/writing.docbook b/doc/writing.docbook
index f33b293..70e09d9 100644
@@ -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.
+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.
+ 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
+ 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.
+ 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.
+ 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.