88 lines
3.3 KiB
XML
88 lines
3.3 KiB
XML
<?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
|
|
its <ulink url="https://git.osgeo.org/gitea/postgis/postgis/raw/branch/master/NEWS">release
|
|
changelog</ulink> first, to find out if your bug has already been
|
|
fixed.</para>
|
|
|
|
<para>Using the <ulink
|
|
url="http://trac.osgeo.org/postgis/">PostGIS bug
|
|
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
|
|
url="http://trac.osgeo.org/postgis">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 patch is definitely
|
|
preferred. This is a four step process on Unix (assuming you already have
|
|
<ulink url="https://git-scm.com/">git</ulink>
|
|
installed):</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Clone the PostGIS' git repository. On Unix,
|
|
type:</para>
|
|
|
|
<para><command>git clone
|
|
https://git.osgeo.org/gitea/postgis/postgis.git</command></para>
|
|
|
|
<para>This will be stored in the directory postgis</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Make your changes to the documentation with your favorite text
|
|
editor. On Unix, type (for example):</para>
|
|
|
|
<para><command>vim doc/postgis.xml</command></para>
|
|
|
|
<para>Note that the documentation is written in DocBook XML 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>git diff 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>
|