<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0">
  <title>Reporting Problems</title>

  <section>
    <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 <link xlink:href="https://git.osgeo.org/gitea/postgis/postgis/raw/branch/master/NEWS">release
    changelog</link> first, to find out if your bug has already been
    fixed.</para>

    <para>Using the <link xlink:href="http://trac.osgeo.org/postgis/">PostGIS bug
    tracker</link> 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 <link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report
    Bugs Effectively</link> before filing a new report.</para>
  </section>

  <section>
    <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 <link xlink:href="http://trac.osgeo.org/postgis">PostGIS bug
    tracker</link>.</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
    <link xlink:href="https://git-scm.com/">git</link>
    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>
  </section>
</chapter>
