diff options
| -rw-r--r-- | doc/howitworks.docbook | 85 | ||||
| -rw-r--r-- | doc/index.docbook | 6 | ||||
| -rw-r--r-- | doc/standalone.docbook | 56 | ||||
| -rw-r--r-- | doc/writing.docbook | 7 |
4 files changed, 154 insertions, 0 deletions
diff --git a/doc/howitworks.docbook b/doc/howitworks.docbook new file mode 100644 index 0000000..773423e --- /dev/null +++ b/doc/howitworks.docbook @@ -0,0 +1,85 @@ +<chapter id="howitworks"> +<title>How it works</title> + +<para> +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. +</para> + +<sect1 id="concepts"> +<title>Concepts</title> + +<para> +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. +</para> + +<variablelist> + <varlistentry> + <term>patchset</term> + <listitem> + + <para> + 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. + </para> + + <para> + The patchsets can be found in the repository inside the patches + directory, or for the installed copy in + /usr/share/autoepatch/patches + <footnote><para> + For alternative prefixes support, see <xref + linkend="prefixsupport" />. + </para></footnote> + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>target</term> + <listitem> + + <para> + 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. + </para> + + <para> + For more informations about target, look at <xref + linkend="writingpatchsets" />. + </para> + + </listitem> + </varlistentry> +</variablelist> + +</sect1> + +<sect1 id="prefixsupport"> +<title>Alternative prefixes support</title> + +<para> +</para> + +</sect1> + +</chapter> diff --git a/doc/index.docbook b/doc/index.docbook index 2793590..dd774dd 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -2,6 +2,9 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd" [ <!ENTITY intro SYSTEM "introduction.docbook"> + <!ENTITY standalone SYSTEM "standalone.docbook"> + <!ENTITY howitworks SYSTEM "howitworks.docbook"> + <!ENTITY writing SYSTEM "writing.docbook"> ]> <book> @@ -11,5 +14,8 @@ </bookinfo> &intro; +&standalone; +&howitworks; +&writing; </book> diff --git a/doc/standalone.docbook b/doc/standalone.docbook new file mode 100644 index 0000000..3c8925a --- /dev/null +++ b/doc/standalone.docbook @@ -0,0 +1,56 @@ +<chapter id="standalone"> +<title>Reasoning for a standalone package</title> + +<para> +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. +</para> + +<para> +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 +at least). +</para> + +<para> +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. +</para> + +<para> +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. +</para> + +<para> +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. +</para> + +</chapter> diff --git a/doc/writing.docbook b/doc/writing.docbook new file mode 100644 index 0000000..96790fb --- /dev/null +++ b/doc/writing.docbook @@ -0,0 +1,7 @@ +<chapter id="writingpatchsets"> +<title>Writing Patchsets</title> + +<para> +</para> + +</chapter> |