1 files changed, 62 insertions, 0 deletions
diff --git a/doc/introduction.docbook b/doc/introduction.docbook
index 865f071..8b85ee5 100644
--- a/doc/introduction.docbook
+++ b/doc/introduction.docbook
@@ -1,6 +1,9 @@
 <chapter id="introduction">
 <title>Introduction</title>
 
+<sect1 id="motivation">
+<title>Motivation</title>
+
 <para>
 To make the software as portable as possible, back in the days, GNU
 created the autoconf package, that allowed them to discover the
@@ -79,4 +82,63 @@ inside Portage itself, so that ebuilds haven't to be aware of its
 presence anymore.
 </para>
 
+</sect1>
+
+<sect1 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>
+
+</sect1>
+
 </chapter>