Add a section about bundled libraries to the Porters Handbook.

Describe why they are considered bad form and what to do about them.

Phabric:	D577
Reviewed by:	wblock
Approved by:	portmgr (mat)

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

@@ -91,6 +91,141 @@
       <filename>/boot/modules</filename>.</para>
   </sect1>
 
+  <sect1 xml:id="bundled-libs">
+    <title>Bundled Libraries</title>
+
+    <para>This section explains why bundled dependencies are
+      considered bad and what to do about them.</para>
+
+    <sect2 xml:id="bundled-libs-why-bad">
+      <title>Why Bundled Libraries Are Bad</title>
+
+      <para>Some software requires the porter to locate third-party
+	libraries and add the required dependencies to the port.
+	Other software bundles all necessary libraries into the
+	distribution file.  The second approach seems easier at
+	first, but there are some serious drawbacks:</para>
+
+      <para>The following list is loosely based on the <link
+	  xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link>
+	and <link
+	  xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link>
+	wikis, both licensed under the <link
+	  xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA
+	  3.0</link> license.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Security</term>
+
+	  <listitem>
+	    <para>If vulnerabilities are found in the upstream library
+	      and fixed there, they might not be fixed in the library
+	      bundled with the port.  One reason could be that the
+	      author is not aware of the problem.  This means that the
+	      porter must fix them, or upgrade to a non-vulnerable
+	      version, and send a patch to the author.  This all takes
+	      time, which results in software being vulnerable longer
+	      than necessary.  This in turn makes it harder to
+	      coordinate a fix without unnecessarily leaking
+	      information about the vulnerability.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Bugs</term>
+
+	  <listitem>
+	    <para>This problem is similar to the problem with security
+	      in the last paragraph, but generally less severe.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Forking</term>
+
+	  <listitem>
+	    <para>It is easier for the author to fork the upstream
+	      library once it is bundled.  While convenient on first
+	      sight, it means that the code diverges from upstream
+	      making it harder to address security or other problems
+	      with the software.  A reason for this is that patching
+	      becomes harder.</para>
+
+	    <para>Another problem of forking is that because code
+	      diverges from upstream, bugs get solved over and over
+	      again instead of just once at a central location.  This
+	      defeats the idea of open source software in the first
+	      place.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Symbol collision</term>
+
+	  <listitem>
+	    <para>When a library is installed on the system, it might
+	      collide with the bundled version.  This can cause
+	      immediate errors at compile or link time.  It can also
+	      cause errors when running the program which might be
+	      harder to track down.  The latter problem could be
+	      caused because the versions of the two libraries are
+	      incompatible.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Licensing</term>
+
+	  <listitem>
+	    <para>When bundling projects from different sources,
+	      license issues can arise more easily, especially when
+	      licenses are incompatible.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Waste of resources</term>
+
+	  <listitem>
+	    <para>Bundled libraries waste resources on several levels.
+	      It takes longer to build the actual application,
+	      especially if these libraries are already present on the
+	      system.  At run-time, they can take up unnecessary
+	      memory when the system-wide library is already loaded by
+	      one program and the bundled library is loaded by another
+	      program.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Waste of effort</term>
+
+	  <listitem>
+	    <para>When a library needs patches for &os;, these patches
+	      have to be duplicated again in the bundled library.
+	      This wastes developer time because the patches might not
+	      apply cleanly.  It can also be hard to notice that these
+	      patches are required in the first place.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2 xml:id="bundled-libs-practices">
+      <title>What to do About Bundled Libraries</title>
+
+      <para>Whenever possible, use the unbundled version of the
+	library by adding a <varname>LIB_DEPENDS</varname> to the
+	port.  If such a port does not exist yet, consider creating
+	it.</para>
+
+      <para>Bundled libraries should only be used if upstream has a
+	good track record on security and using unbundled versions
+	leads to overly complex patches.</para>
+    </sect2>
+  </sect1>
+
   <sect1 xml:id="porting-shlibs">
     <title>Shared Libraries</title>