2008-07-08 05:09:36 +00:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<chapter>
|
|
|
|
<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
|
|
|
|
developers to reproduce it, so it would ideally contain a script
|
|
|
|
triggering it and every information regarding the environment in which it
|
|
|
|
was detected. Good enough info can be extracted running <code>SELECT
|
|
|
|
postgis_full_version()</code> [for postgis] and <code>SELECT
|
|
|
|
version()</code> [for postgresql].</para>
|
|
|
|
|
|
|
|
<para>If you aren't using the latest release, it's worth taking a look at
|
2009-10-28 10:58:33 +00:00
|
|
|
its <ulink url="http://svn.osgeo.org/postgis/trunk/NEWS">release
|
2008-07-08 05:09:36 +00:00
|
|
|
changelog</ulink> first, to find out if your bug has already been
|
|
|
|
fixed.</para>
|
|
|
|
|
|
|
|
<para>Using the <ulink
|
2009-10-28 10:58:33 +00:00
|
|
|
url="http://trac.osgeo.org/postgis/">PostGIS bug
|
2008-07-08 05:09:36 +00:00
|
|
|
tracker</ulink> will ensure your reports are not discarded, and will 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
|
2009-10-28 10:58:33 +00:00
|
|
|
url="http://trac.osgeo.org/postgis">PostGIS bug
|
2008-07-08 05:09:36 +00:00
|
|
|
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
|
2009-10-28 10:58:33 +00:00
|
|
|
http://svn.osgeo.org/postgis/trunk/</command></para>
|
2008-07-08 05:09:36 +00:00
|
|
|
|
|
|
|
<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>
|
|
|
|
|
2009-10-28 10:58:33 +00:00
|
|
|
<para><command>vim trunk/doc/postgis.xml</command></para>
|
2008-07-08 05:09:36 +00:00
|
|
|
|
|
|
|
<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.</para>
|
|
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|