Chapter 15. Reporting Problems

Table of Contents
15.1. Reporting Software Bugs
15.2. Reporting Documentation Issues

15.1. Reporting Software Bugs

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 SELECT postgis_full_version() [for postgis] and SELECT version() [for postgresql].

If you aren't using the latest release, it's worth taking a look at its release changelog first, to find out if your bug has already been fixed.

Using the PostGIS bug tracker 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.

You might want to read Simon Tatham's paper about How to Report Bugs Effectively before filing a new report.

15.2. Reporting Documentation Issues

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.

Documentation issues can also be reported to the PostGIS bug tracker.

If your revision is trivial, just describe it in a new bug tracker issue, being specific about its location in the documentation.

If your changes are more extensive, a patch is definitely preferred. This is a four step process on Unix (assuming you already have Git installed):

  1. Check out a copy of PostGIS' git master. On Unix, type:

    git clone https://git.osgeo.org/gitea/postgis/postgis.git postgis

    This will be stored in the directory postgis

    Note if you need to switch to another branch for testing such as latest stable or tagged you can do:

    cd postgis git checkout stable-3.0

  2. Make your changes to the documentation with your favorite text editor. On Unix, type (for example):

    vim doc/postgis.xml

    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.

  3. Make a patch file containing the differences from the master copy of the documentation. On Unix, type:

    git diff doc/postgis.xml > doc.patch

  4. Attach the patch to a new issue in bug tracker.