<?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 &gt;
        doc.patch</command></para>
      </listitem>

      <listitem>
        <para>Attach the patch to a new issue in bug tracker.</para>
      </listitem>
    </orderedlist>
  </sect1>
</chapter>
