Add some more GNOME-specific packaging and porting information:

- Document how to handle .desktop files.
- Document how to handle icons for the hicolor theme.
- Add a chapter detailing the GNOME meta packages, the packaging of new
  applications and the updatee procedure.

Also add some documentation on how to better handle and create patches.

5 files changed, 563 insertions, 22 deletions

diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 6edfc5aee17..e0321a1345b 100644
--- a/doc/guide/files/chapters.ent
+++ b/doc/guide/files/chapters.ent
@@ -1,7 +1,7 @@
 <!--
 	Creates entities for each chapter in the pkgsrc book.
 
-	$NetBSD: chapters.ent,v 1.14 2006/07/03 23:51:01 rillig Exp $
+	$NetBSD: chapters.ent,v 1.15 2006/09/01 16:35:38 jmmv Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -28,6 +28,7 @@
 <!ENTITY chap.debug			SYSTEM "debug.xml">
 <!ENTITY chap.submit			SYSTEM "submit.xml">
 <!ENTITY chap.devfaq			SYSTEM "devfaq.xml">
+<!ENTITY chap.gnome			SYSTEM "gnome.xml">
 
 <!-- The pkgsrc infrastructure -->
 <!ENTITY chap.infr.design		SYSTEM "infr.design.xml">
diff --git a/doc/guide/files/components.xml b/doc/guide/files/components.xml
index 52814689bbd..b2362624ec5 100644
--- a/doc/guide/files/components.xml
+++ b/doc/guide/files/components.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.26 2006/07/24 10:32:36 rillig Exp $ -->
+<!-- $NetBSD: components.xml,v 1.27 2006/09/01 16:35:38 jmmv Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
   <title>Package components - files, directories and contents</title>
@@ -239,12 +239,6 @@
       for the patch files by using the <command>make makepatchsum</command>
       command, see <xref linkend="components.distinfo"/>.</para>
 
-    <para>When adding a patch that corrects a problem in the distfile (rather
-      than e.g. enforcing pkgsrc's view of where man pages should go), send
-      the patch as a bug report to the maintainer.  This benefits
-      non-pkgsrc users of the package, and usually enables removing
-      the patch in future version.</para>
-
     <para>Patch files that are distributed by the author or other
       maintainers can be listed in
       <varname>$PATCHFILES</varname>. </para>
@@ -261,6 +255,143 @@
       it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
       files in the named directory are expected to be patch files, and
       <emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para>
+
+    <sect2 id="components.patches.guidelines">
+      <title>Patching guidelines</title>
+
+      <para>When fixing a portability issue in the code do not use
+      preprocessor magic to check for the current operating system nor
+      platform.  Doing so hurts portability to other platforms because
+      the OS-specific details are not abstracted appropriately.</para>
+      
+      <para>The general rule to follow is: instead of checking for the
+      operating system the application is being built on, check for the
+      specific <emphasis>features</emphasis> you need.  For example,
+      instead of assuming that kqueue is available under NetBSD and
+      using the <varname>__NetBSD__</varname> macro to conditionalize
+      kqueue support, add a check that detects kqueue itself &mdash;
+      yes, this generally involves patching the
+      <command>configure</command> script.  There is absolutely nothing
+      that prevents some OSes from adopting interfaces from other OSes
+      (e.g. Linux implementing kqueue), something that the above checks
+      cannot take into account.</para>
+      
+      <para>Of course, checking for features generally involves more
+      work on the developer's side, but the resulting changes are
+      clearner and there are chances they will work on many other
+      platforms.  Not to mention that there are higher chances of being
+      later integrated into the mainstream sources.  Remember:
+      <emphasis>It doesn't work unless it is right!</emphasis></para>
+
+      <para>Some typical examples:</para>
+
+      <table id="patch-examples">
+	<title>Patching examples</title>
+
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Where</entry>
+	      <entry>Incorrect</entry>
+	      <entry>Correct</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>configure script</entry>
+	      <entry>
+		<programlisting>case ${target_os} in
+      netbsd*) have_kvm=yes ;;
+      *)       have_kvm=no  ;;
+  esac</programlisting>
+	      </entry>
+
+	      <entry>
+		<programlisting>AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)</programlisting>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>C source file</entry>
+	      <entry>
+		<programlisting>#if defined(__NetBSD__)
+  #  include &lt;sys/event.h&gt;
+  #endif</programlisting>
+	      </entry>
+	      <entry>
+		<programlisting>#if defined(HAVE_SYS_EVENT_H)
+  #  include &lt;sys/event.h&gt;
+  #endif</programlisting>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>C source file</entry>
+	      <entry><programlisting>int
+  monitor_file(...)
+  {
+  #if defined(__NetBSD__)
+      int fd = kqueue();
+      ...
+  #else
+      ...
+  #endif
+  }</programlisting>
+	      </entry>
+	      <entry>
+		<programlisting>int
+  monitor_file(...)
+  {
+  #if defined(HAVE_KQUEUE)
+      int fd = kqueue();
+      ...
+  #else
+      ...
+  #endif
+  }</programlisting>
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <para>For more information, please read the <emphasis>Making
+      packager-friendly software</emphasis> article (<ulink
+      url="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html">part
+      1</ulink>, <ulink
+      url="http://www.oreillynet.com/pub/a/onlamp/2005/04/28/packaging2.html">part
+      2</ulink>).  It summarizes multiple details on how to make
+      software easier to package; all the suggestions in it were
+      collected from our experience in pkgsrc work, so they are possibly
+      helpful when creating patches too.</para>
+
+    </sect2>
+
+    <sect2 id="components.patches.feedback">
+      <title>Feedback to the author</title>
+
+      <para>Always, always, <emphasis role="strong">always</emphasis>
+      feed back any <emphasis>portability fixes</emphasis> or
+      improvements you do to a package to the mainstream developers.
+      This is the only way to get their attention on portability issues
+      and to ensure that future versions can be built out-of-the box on
+      NetBSD.  Furthermore, any user that gets newer distfiles will get
+      the fixes straight from the packaged code.</para>
+
+      <para>This generally involves cleaning up the patches as described
+      in the following section (because sometimes the patches that are
+      added to pkgsrc are quick hacks), filling bug reports in the
+      appropriate trackers for the projects and working with the
+      mainstream authors to accept your changes.  It is
+      <emphasis>extremely important</emphasis> that you do it so that
+      the packages in pkgsrc are kept simple and thus further changes
+      can be done without much hassle.</para>
+
+      <para>Support the idea of free software!</para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="other-mandatory-files">
diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index b1e99f886c9..89e5ece6953 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.68 2006/08/12 21:29:40 wiz Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.69 2006/09/01 16:35:38 jmmv Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Making your package work</title>
@@ -1639,20 +1639,68 @@ Changes to the PLIST
       </orderedlist>
     </sect2>
 
-  </sect1>
 
+    <sect2 id="hicolor-theme">
+      <title>Packages installing hicolor theme icons</title>
+
+      <para>If a package installs images under the
+      <filename>share/icons/hicolor</filename> and/or updates the
+      <filename>share/icons/hicolor/icon-theme.cache</filename> database,
+      you need to take some extra steps to make sure that the shared
+      theme directory is handled appropriately and that the cache
+      database is rebuilt:</para>
+
+      <orderedlist>
+        <listitem>
+	  <para>Include
+	  <filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>
+	  instead of its <filename>buildlink3.mk</filename> file.</para>
+        </listitem>
+
+        <listitem>
+          <para>Check the PLIST and remove the entry that refers to the
+	  theme cache.</para>
+        </listitem>
 
-  <sect1 id="feedback-to-author">
-    <title>Feedback to the author</title>
+        <listitem>
+	  <para>Ensure that the PLIST does not remove the shared icon
+	  directories from the <filename>share/icons/hicolor</filename>
+	  hierarchy because they will be handled automatically.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>The best way to verify that the PLIST is correct with
+      respect to the last two points is to regenerate it using
+      <command>make print-PLIST</command>.</para>
+    </sect2>
 
-    <para>If you have found any bugs in the package you make available,
-      if you had to do special steps to make it run under NetBSD or
-      if you enhanced the software in various other ways, be sure
-      to report these changes back to the original author of the
-      program! With that kind of support, the next release of the
-      program can incorporate these fixes, and people not using the
-      NetBSD packages system can win from your efforts.</para>
 
-    <para>Support the idea of free software!</para>
+    <sect2 id="desktop-files">
+      <title>Packages installing desktop files</title>
+
+      <para>If a package installs <filename>.desktop</filename> files
+      under <filename>share/applications</filename> and these include
+      MIME information, you need to take extra steps to ensure that they
+      are registered into the MIME database:</para>
+
+      <orderedlist>
+        <listitem>
+	  <para>Include
+	  <filename>../../sysutils/desktop-file-utils/desktopdb.mk</filename>.</para>
+        </listitem>
+
+        <listitem>
+          <para>Check the PLIST and remove the entry that refers to the
+	  <filename>share/applications/mimeinfo.cache</filename> file.
+	  It will be handled automatically.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>The best way to verify that the PLIST is correct with
+      respect to the last point is to regenerate it using <command>make
+      print-PLIST</command>.</para>
+    </sect2>
+
   </sect1>
+
 </chapter>
diff --git a/doc/guide/files/gnome.xml b/doc/guide/files/gnome.xml
new file mode 100644
index 00000000000..7f89258e43c
--- /dev/null
+++ b/doc/guide/files/gnome.xml
@@ -0,0 +1,360 @@
+<!-- $NetBSD: gnome.xml,v 1.1 2006/09/01 16:35:39 jmmv Exp $ -->
+
+<chapter id="gnome"> <?dbhtml filename="gnome.html"?>
+<title>GNOME packaging and porting</title>
+
+<para>Quoting <ulink url="http://www.gnome.org/">GNOME's web
+site</ulink>:</para>
+
+<blockquote>
+  <para>The GNOME project provides two things: The GNOME desktop
+  environment, an intuitive and attractive desktop for users, and the
+  GNOME development platform, an extensive framework for building
+  applications that integrate into the rest of the desktop.</para>
+</blockquote>
+
+<para>pkgsrc provides a seamless way to automatically build and install
+a complete GNOME environment <emphasis>under many different
+platforms</emphasis>.  We can say with confidence that pkgsrc is one of
+the most advanced build and packaging systems for GNOME due to its
+included technologies buildlink3, the wrappers and tools framework and
+automatic configuration file management.  Lots of efforts are put into
+achieving a completely clean deinstallation of installed software
+components.</para>
+
+<para>Given that pkgsrc is <ulink
+url="http://www.NetBSD.org/">NetBSD</ulink>'s official packaging system,
+the above also means that great efforts are put into making GNOME work
+under this operating system.  Recently, <ulink
+url="http://www.dragonflybsd.org/">DragonFly BSD</ulink> also adopted
+pkgsrc as its preferred packaging system, contributing lots of
+portability fixes to make GNOME build and install under it.</para>
+
+<para>This chapter is aimed at pkgsrc developers and other people
+interested in helping our GNOME porting and packaging efforts.  It
+provides instructions on how to manage the existing packages and some
+important information regarding their internals.</para>
+
+<note>
+  <title>We need your help!</title>
+
+  <para>Should you have some spare cycles to devote to NetBSD, pkgsrc
+  and GNOME and are willing to learn new exciting stuff, please jump
+  straight to the <ulink
+  url="http://www.NetBSD.org/contrib/projects.html#gnome">pending
+  work</ulink> list!  There is still a long way to go to get a
+  fully-functional GNOME desktop under NetBSD and we need your help to
+  achieve it!</para>
+</note>
+
+<sect1 id="meta-packages">
+<title>Meta packages</title>
+
+<para>pkgsrc includes three GNOME-related meta packages:</para>
+
+<itemizedlist>
+  <listitem>
+    <para><filename role="pkg">meta-pkgs/gnome-base</filename>: Provides
+    the core GNOME desktop environment.  It only includes the necessary
+    bits to get it to boot correctly, although it may lack important
+    functionality for daily operation.  The idea behind this package is
+    to let end users build their own configurations on top of this one,
+    first installing this meta package to achieve a functional setup and
+    then adding individual applications.</para>
+  </listitem>
+
+  <listitem>
+    <para><filename role="pkg">meta-pkgs/gnome</filename>: Provides a
+    complete installation of the GNOME platform and desktop as defined
+    by the GNOME project; this is based on the components distributed in
+    the <filename>platform/x.y/x.y.z/sources</filename> and
+    <filename>desktop/x.y/x.y.z/sources</filename> directories of the
+    official FTP server.  Developer-only tools found in those
+    directories are not installed unless required by some other
+    component to work properly.  Similarly, packages from the bindings
+    set (<filename>bindings/x.y/x.y.z/sources</filename>) are not pulled
+    in unless required as a dependency for an end-user component.  This
+    package "extends" <filename
+    role="pkg">meta-pkgs/gnome-base</filename>.</para>
+  </listitem>
+
+  <listitem>
+    <para><filename role="pkg">meta-pkgs/gnome-devel</filename>:
+    Installs all the tools required to build a GNOME component when
+    fetched from the CVS repository.  These are required to let the
+    <command>autogen.sh</command> scripts work appropriately.</para>
+  </listitem>
+</itemizedlist>
+
+<para>In all these packages, the <varname>DEPENDS</varname> lines are
+sorted in a way that eases updates: a package may depend on other
+packages listed before it but not on any listed after it.  It is very
+important to keep this order to ease updates so... <emphasis>do not
+change it to alphabetical sorting!</emphasis></para>
+
+</sect1>
+
+<sect1 id="new-package">
+<title>Packaging a GNOME application</title>
+
+<para>Almost all GNOME applications are written in C and use a common
+set of tools as their build system.  Things get different with the new
+bindings to other languages (such as Python), but the following will
+give you a general idea on the minimum required tools:</para>
+
+<itemizedlist>
+  <listitem>
+    <para>Almost all GNOME applications use the GNU Autotools as their
+    build system.  As a general rule you will need to tell this to your
+    package:</para>
+
+    <programlisting>GNU_CONFIGURE=yes
+USE_LIBTOOL=yes
+USE_TOOLS+=gmake</programlisting>
+  </listitem>
+
+  <listitem>
+    <para>If the package uses pkg-config to detect dependencies, add this
+    tool to the list of required utilities:</para>
+
+    <programlisting>USE_TOOLS+=pkg-config</programlisting>
+
+    <para>Also use <filename role="pkg">pkgtools/verifypc</filename> at
+    the end of the build process to ensure that you did not miss to
+    specify any dependency in your package and that the version
+    requirements are all correct.</para>
+  </listitem>
+
+  <listitem>
+    <para>If the package uses intltool, be sure to include the <filename
+    role="cvsweb">pkgsrc/textproc/intltool/buildlink3.mk</filename> file
+    to handle dependencies and to force the package to use the latest
+    available version.</para>
+  </listitem>
+
+  <listitem>
+    <para>If the package uses gtk-doc (a documentation generation
+    utility), do <emphasis>not</emphasis> add a dependency on it.  The
+    tool is rather big and the distfile should come with pregenerated
+    documentation anyway; if it does not, it is a bug that you ought to
+    report.  For such packages you should disable gtk-doc (unless it is
+    the default) and change the location of installed HTML files:</para>
+
+    <programlisting>CONFIGURE_ARGS+=--disable-gtk-doc
+CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/doc</programlisting>
+  </listitem>
+</itemizedlist>
+
+<para>GNOME uses multiple <emphasis>shared</emphasis> directories and
+files under the installation prefix to maintain databases.  In this
+context, shared means that those exact same directories and files are
+used among several different packages, leading to conflicts in the
+<filename>PLIST</filename>.  pkgsrc currently includes functionality to
+handle the most common cases, so you have to forget about using
+<literal>@unexec ${RMDIR}</literal> lines in your file lists and
+omitting shared files from them.  If you find yourself doing those,
+<emphasis>your package is most likely incorrect</emphasis>.</para>
+
+<para>The following table lists the common situations that result in
+using shared directories or files.  For each of them, the appropriate
+solution is given.  After applying the solution be sure to
+<emphasis>regenerate the package's file list</emphasis> with
+<command>make print-PLIST</command> and ensure it is correct.</para>
+
+<table id="plist-handling">
+  <title>PLIST handling for GNOME packages</title>
+
+  <tgroup cols="2">
+    <thead>
+      <row>
+        <entry>If the package...</entry>
+        <entry>Then...</entry>
+      </row>
+    </thead>
+
+    <tbody>
+      <row>
+        <entry>Installs OMF files under <filename>share/omf</filename>.</entry>
+        <entry>See <xref linkend="scrollkeeper-data-files" />.</entry>
+      </row>
+
+      <row>
+        <entry>Installs icons under the
+        <filename>share/icons/hicolor</filename> hierarchy or updates
+        <filename>share/icons/hicolor/icon-theme.cache</filename>.</entry>
+        <entry>See <xref linkend="hicolor-theme" />.</entry>
+      </row>
+
+      <row>
+        <entry>Installs files under
+        <filename>share/mime/packages</filename>.</entry>
+        <entry>See <xref linkend="mime-database" />.</entry>
+      </row>
+
+      <row>
+        <entry>Installs <filename>.desktop</filename> files under
+        <filename>share/applications</filename> and these include MIME
+        information.</entry>
+        <entry>See <xref linkend="desktop-files" />.</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</table>
+
+</sect1>
+
+<sect1 id="full-update">
+<title>Updating GNOME to a newer version</title>
+
+<para>When seeing GNOME as a whole, there are two kinds of
+updates:</para>
+
+<variablelist>
+  <varlistentry>
+    <term>Major update</term>
+    
+    <listitem>
+      <para>Given that there is still a very long way for GNOME 3 (if it
+      ever appears), we consider a major update one that goes from a
+      <literal>2.X</literal> version to a <literal>2.Y</literal> one,
+      where <literal>Y</literal> is even and greater than
+      <literal>X</literal>.  These are hard to achieve because they
+      introduce lots of changes in the components' code and almost all
+      GNOME distfiles are updated to newer versions.  Some of them can
+      even break API and ABI compatibility with the previous major
+      version series.  As a result, the update needs to be done all at
+      once to minimize breakage.</para>
+
+      <para>A major update typically consists of around 80 package
+      updates and the addition of some new ones.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>Minor update</term>
+    
+    <listitem>
+      <para>We consider a minor update one that goes from a
+      <literal>2.A.X</literal> version to a <literal>2.A.Y</literal>
+      one where <literal>Y</literal> is greater than
+      <literal>X</literal>.  These are easy to achieve because they do
+      not update all GNOME components, can be done in an incremental way
+      and do not break API nor ABI compatibility.</para>
+
+      <para>A minor update typically consists of around 50 package
+      updates, although the numbers here may vary a lot.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>In order to update the GNOME components in pkgsrc to a new stable
+release (either major or minor), the following steps should be
+followed:</para>
+
+<orderedlist>
+  <listitem>
+    <para>Get a list of all the tarballs that form the new release by
+    using the following commands.  These will leave the full list of the
+    components's distfiles into the <filename>list.txt</filename>
+    file:</para>
+
+    <screen><prompt>$ </prompt><userinput>echo ls "*.tar.bz2" | \
+    ftp -V ftp://ftp.gnome.org/pub/gnome/platform/x.y/x.y.z/sources/ | \
+    awk '{ print $9 }' &gt;list.txt</userinput>
+<prompt>$ </prompt><userinput>echo ls "*.tar.bz2" | \
+    ftp -V ftp://ftp.gnome.org/pub/gnome/desktop/x.y/x.y.z/sources/ | \
+    awk '{ print $9 }' &gt;&gt;list.txt</userinput></screen>
+  </listitem>
+
+  <listitem>
+    <para>Open each meta package's <filename>Makefile</filename> and
+    bump their version to the release you are updating them to.  The
+    three meta packages should be always consistent with versioning.
+    Obviously remove any <varname>PKGREVISION</varname>s that might be
+    in them.</para>
+  </listitem>
+ 
+  <listitem>
+    <para>For each meta package, update all its
+    <varname>DEPENDS</varname> lines to match the latest versions as
+    shown by the above commands.  Do <emphasis>not</emphasis> list any
+    newer version (even if found in the FTP) because the meta packages
+    are supposed to list the exact versions that form a specific GNOME
+    release.  Exceptions are permitted here if a newer version solves a
+    serious issue in the overall desktop experience; these typically
+    come in the form of a revision bump in pkgsrc, not in newer versions
+    from the developers.</para>
+
+    <para>Packages not listed in the <filename>list.txt</filename> file
+    should be updated to the latest version available (if found in
+    pkgsrc).  This is the case, for example, of the dependencies on the
+    GNU Autotools in the <filename
+    role="pkg">meta-pkgs/gnome-devel</filename> meta package.</para>
+  </listitem>
+
+  <listitem>
+    <para>Generate a patch from the modified meta packages and extract the
+    list of "new" lines.  This will provide you an outline on what
+    packages need to be updated in pkgsrc and in what order:</para>
+
+    <screen><prompt>$ </prompt><userinput>cvs diff gnome-devel gnome-base gnome | grep '^+D' &gt;todo.txt</userinput></screen>
+  </listitem>
+
+  <listitem>
+    <para>For major desktop updates it is recommended to zap all your
+    installed packages and start over from scratch at this point.</para>
+  </listitem>
+
+  <listitem>
+    <para>Now comes the longest step by far: iterate over the contents
+    of <filename>todo.txt</filename> and update the packages listed in
+    it in order.  For major desktop updates none of these should be
+    commited until the entire set is completed because there are chances
+    of breaking not-yet-updated packages.</para>
+  </listitem>
+
+  <listitem>
+    <para>Once the packages are up to date and working, commit them to
+    the tree one by one with appropriate log messages.  At the end,
+    commit the three meta package updates and all the corresponding
+    changes to the <filename>doc/CHANGES-&lt;YEAR&gt;</filename> and
+    <filename role="cvsweb">pkgsrc/doc/TODO</filename> files.</para>
+  </listitem>
+</orderedlist>
+
+</sect1>
+
+<sect1 id="patching">
+<title>Patching guidelines</title>
+
+<para>GNOME is a very big component in pkgsrc which approaches 100
+packages.  Please, it is very important that you always, always,
+<emphasis role="strong">always</emphasis> feed back any portability
+fixes you do to a GNOME package to the mainstream developers (see <xref
+linkend="components.patches.feedback" />).  This is the only way to get
+their attention on portability issues and to ensure that future versions
+can be built out-of-the box on NetBSD.  The less custom patches in
+pkgsrc, the easier further updates are.  Those developers in charge of
+issuing major GNOME updates will be grateful if you do that.</para>
+
+<para>The most common places to report bugs are the <ulink
+url="http://bugzilla.gnome.org/">GNOME's Bugzilla</ulink> and the <ulink
+url="http://bugzilla.freedesktop.org/">freedesktop.org's
+Bugzilla</ulink>.  Not all components use these to track bugs, but most
+of them do.  Do not be short on your reports: always provide detailed
+explanations of the current failure, how it can be improved to achieve
+maximum portability and, if at all possible, provide a patch against CVS
+head.  The more verbose you are, the higher chances of your patch being
+accepted.</para>
+
+<para>Also, please avoid using preprocessor magic to fix portability
+issues.  While the FreeBSD GNOME people are doing a great job in porting
+GNOME to their operating system, the official GNOME sources are now
+plagued by conditionals that check for <varname>__FreeBSD__</varname>
+and similar macros.  This hurts portability.  Please see our patching
+guidelines (<xref linkend="components.patches.guidelines" />) for more
+details.</para>
+
+</sect1>
+
+</chapter>
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index d351ef8d2fb..09216d85897 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.21 2006/07/03 23:51:01 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.22 2006/09/01 16:35:39 jmmv Exp $ -->
 
 
 <?xml version="1.0"?>
@@ -45,7 +45,7 @@
       <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.21 2006/07/03 23:51:01 rillig Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.22 2006/09/01 16:35:39 jmmv Exp $</pubdate>
 
     <abstract>
 
@@ -93,6 +93,7 @@
     &chap.debug;
     &chap.submit;
     &chap.devfaq;
+    &chap.gnome;
   </part>
 
   <!-- The pkgsrc infrastructure -->