|author||Diego Elio Pettenò <firstname.lastname@example.org>||2006-12-30 07:12:12 +0000|
|committer||Diego Elio Pettenò <email@example.com>||2006-12-30 07:12:12 +0000|
|parent||Add id value. (diff)|
Add a chapter on the reasons why a standalone package was chosen instead of other solutions, and start one about the way autoepatch works.
svn path=/trunk/; revision=24
4 files changed, 154 insertions, 0 deletions
diff --git a/doc/howitworks.docbook b/doc/howitworks.docbook
new file mode 100644
@@ -0,0 +1,85 @@
+<title>How it works</title>
+In this chapter, we'll try to explain how autoepatch works, and how to
+extend it to patch and fix new problems. The reason to provide a
+throughout documentation about this is to make the maintainership of
+autoepatch simpler, so that if the developers currently involved in
+its writing would not be available, newcomers won't have to read all
+the code to find how it actually works.
+There aren't many concepts to describe on autoepatch because it is,
+basically, a simple set of scripts. The definitions that will be given
+here are not even proper "concepts" but this section is intented to
+clear up the terminology used, so that there can't be misunderstanding
+in the next sections and chapters.
+ With this term, the documentation will refer to a set of scripts
+ and actual patches, the base element handled by autoepatch itself.
+ Despite the name used seem to limit a patchset to just patches,
+ it's well possible that a patchset has no actual ".patch" file,
+ and instead consist of a single shell script that describes the
+ changes to apply to targets.
+ The patchsets can be found in the repository inside the patches
+ directory, or for the installed copy in
+ For alternative prefixes support, see <xref
+ linkend="prefixsupport" />.
+ Under this name we consider a file, or a directory, on which the
+ patchset applies. When the target is a directory, ad the patchset
+ contains actual patches, the paths inside the patches should refer
+ to the direct name of the files starting from the target directory
+ (-p0 option to gpatch); when the target is a file instead, the
+ patch will apply directly over the file. When instead the patchset
+ consist of a function (or a series of functions), the target is
+ passed as parameter, whichever the type it is.
+ For more informations about target, look at <xref
+ linkend="writingpatchsets" />.
+<title>Alternative prefixes support</title>
diff --git a/doc/index.docbook b/doc/index.docbook
index 2793590..dd774dd 100644
@@ -2,6 +2,9 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<!ENTITY intro SYSTEM "introduction.docbook">
+ <!ENTITY standalone SYSTEM "standalone.docbook">
+ <!ENTITY howitworks SYSTEM "howitworks.docbook">
+ <!ENTITY writing SYSTEM "writing.docbook">
@@ -11,5 +14,8 @@
diff --git a/doc/standalone.docbook b/doc/standalone.docbook
new file mode 100644
@@ -0,0 +1,56 @@
+<title>Reasoning for a standalone package</title>
+There are many ways to accomplish the same result. Why the choice was
+done toward a standalone package, that would require a new ebuild, and
+a tarball, and so on? There are a series of reasons why this approach
+is probably the best compromise between the weight of maintainership
+and the ability to do changes without involving all the users at once.
+The current method, of storing both the logic code and the patches on
+the same CVS module used for the portage tree, and thus on the RSync
+servers, is obviously flawed: the eclass has to know the PORTDIR path,
+there's no way to overlay the patches if one has to be changed for
+some reason; the code applies to all users at the same time, as the
+eclass is not versioned for stable and testing branches; the size of
+patches and logic code is restricted, because the size of the CVS tree
+is a main concern, as it already increases with the increase of the
+number of packages available; there's no security because neither the
+eclasses nor the patches are signed or signable (at the current time
+Another option would be to ship the logic code with either a
+standalone package or portage and then ship the patches with the RSync
+tree, but this leaves us with the security issue (although it might be
+possible to find a solution to this), and with the size constraints
+that we have with the current solution. Even if it would be possible
+to just recode the logic to allow a separation between testing and
+stable packages, it would be difficult to tell from an emerge --info
+output what the user is using for a given package.
+By using a separate standalone package it is possible to avoid limits
+on the size of both the logic and the patches (that would be on their
+own archive, which could just have a "reasonable size"), it is
+possible to sign the ebuild in the tree, and thus the digest for the
+tarball would be signed too, covering the security issue; there can be
+different versions of the tarball, with different patches, that can
+have different visibility depending on keywords and masked state, and
+it can be easily told by an emerge --info which version of the package
+is used once the profiles are instructed to.
+Probably the worst drawback is that there's the need of a standalone
+repository to contain the logic and the patches, but also this can be
+considered an advantage as that allows us to branch it when moving to
+a stable target.
diff --git a/doc/writing.docbook b/doc/writing.docbook
new file mode 100644
@@ -0,0 +1,7 @@