1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
<!-- 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 >
doc.patch</command></para>
</listitem>
<listitem>
<para>Attach the patch to a new issue in bug tracker.</para>
</listitem>
</orderedlist>
</section>
</chapter>
|
