From 08263950ccba18fa90b9ab5e975edfbbe711915a Mon Sep 17 00:00:00 2001 From: Diego Elio Pettenò Date: Sat, 30 Dec 2006 07:12:12 +0000 Subject: 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 --- doc/howitworks.docbook | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.docbook | 6 ++++ doc/standalone.docbook | 56 +++++++++++++++++++++++++++++++++ doc/writing.docbook | 7 +++++ 4 files changed, 154 insertions(+) create mode 100644 doc/howitworks.docbook create mode 100644 doc/standalone.docbook create mode 100644 doc/writing.docbook 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 @@ + +How it works + + +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. + + + +Concepts + + +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. + + + + + patchset + + + + 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 + /usr/share/autoepatch/patches + + For alternative prefixes support, see . + + + + + + + + target + + + + 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 . + + + + + + + + + +Alternative prefixes support + + + + + + + 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 @@ + + + ]> @@ -11,5 +14,8 @@ &intro; +&standalone; +&howitworks; +&writing; 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 @@ + +Reasoning for a standalone package + + +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 +at least). + + + +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 index 0000000..96790fb --- /dev/null +++ b/doc/writing.docbook @@ -0,0 +1,7 @@ + +Writing Patchsets + + + + + -- cgit v1.2.3-65-gdbad