[postgis-commits] svn - r2789 - trunk/doc

[postgis-commits at postgis.refractions.net]

Author: pramsey
Date: 2008-05-28 14:45:01 -0700 (Wed, 28 May 2008)
New Revision: 2789

Modified:
   trunk/doc/postgis.xml
Log:
Bug reporting documentation (issue 27)


Modified: trunk/doc/postgis.xml
===================================================================
--- trunk/doc/postgis.xml	2008-05-28 21:35:53 UTC (rev 2788)
+++ trunk/doc/postgis.xml	2008-05-28 21:45:01 UTC (rev 2789)
@@ -6072,7 +6072,9 @@
   </chapter>
 
   <chapter>
-    <title>Reporting Bugs</title>
+    <title>Reporting Problems</title>
+    <sect1>
+      <title>Reporting Software Bugs</title>
 
     <para>Reporting bugs effectively is a fundamental way to help PostGIS
     development. The most effective bug report is that enabling PostGIS
@@ -6082,19 +6084,71 @@
     postgis_full_version()</code> [for postgis] and <code>SELECT version()</code>
     [for postgresql].</para>
 
-    <para>If you aren't using latest release, it's worth taking a look
+    <para>If you aren't using the latest release, it's worth taking a look
     at its <ulink url="http://postgis.refractions.net/CHANGES.txt">release
     changelog</ulink> first, to find out if your bug has already been fixed.</para>
 
     <para>Using the <ulink url="http://code.google.com/p/postgis/issues/list">PostGIS
     bug tracker</ulink> will ensure your reports are not discarded, and will
-    keep you informed on it's handling process. Before reporting a new bug
+    keep you informed on its handling process. Before reporting a new bug
     please query the database to see if it is a known one, and if it is please
     add any new information you have about it.</para>
 
     <para>You might want to read Simon Tatham's paper about <ulink
     url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report
     Bugs Effectively</ulink> before filing a new report.</para>
+    </sect1>
+    <sect1>
+      <title>Reporting Documentation Issues</title>
+
+        <para>The documentation should accurately reflect the features and
+        behavior of the software. If it doesn't, it could be because of a software bug or
+        because the documentation is in error or deficient.</para>
+
+        <para>Documentation issues can also be reported to the
+        <ulink url="http://code.google.com/p/postgis/issues/list">PostGIS bug tracker</ulink>.</para>
+
+       <para>If your revision is trivial, just describe it in a new bug tracker issue,
+        being specific about its location in the documentation.</para>
+
+       <para>If your changes are more extensive, a Subversion patch is definitely preferred.
+       This is a four step process on Unix (assuming you already have
+       <ulink url="http://subversion.tigris.org/">Subversion</ulink> installed):</para>
+
+        <orderedlist>
+          <listitem>
+
+           <para>Check out a copy of PostGIS' Subversion trunk. On Unix, type:</para>
+
+            <para><command>svn checkout http://svn.refractions.net/postgis/trunk/</command></para>
+
+           <para>This will be stored in the directory ./trunk </para>
+          </listitem>
+          <listitem>
+
+           <para>Make your changes to the documentation with your favorite text editor. On Unix, type (for example):</para>
+
+            <para><command>vi trunk/doc/postgis.xml</command></para>
+
+           <para>Note that the documentation is written in SGML rather than HTML,
+            so if you are not familiar with it please follow the example of the rest of the documentation.</para>
+
+          </listitem>
+          <listitem>
+
+           <para>Make a patch file containing the differences from the master copy of the documentation. On Unix, type:</para>
+
+            <para><command>svn diff trunk/doc/postgis.xml > doc.patch</command></para>
+
+          </listitem>
+          <listitem>
+
+            <para>Attach the patch to a new issue in bug tracker.</command></para>
+
+          </listitem>
+        </orderedlist>
+
+    </sect1>
   </chapter>
 
   <appendix id="release_notes">