devel-docs/bugs.rst - New chapter on reporting bugs

2 files changed, 52 insertions, 0 deletions

diff --git a/devel-docs/bugs.rst b/devel-docs/bugs.rst
new file mode 100644
index 00000000..efc34c67
--- /dev/null
+++ b/devel-docs/bugs.rst
@@ -0,0 +1,50 @@
+Reporting bugs
+==============
+
+Please report bugs at https://gitlab.gnome.org/GNOME/librsvg/issues
+
+If you want to report a rendering bug, or a missing SVG feature,
+please provide an example SVG file as an attachment to your bug
+report.  It really helps if you can minimize the SVG to only the
+elements required to reproduce the bug or see the missing feature, but
+it is not absolutely required.  **Please be careful** of publishing
+SVG images that you don't want other people to see, or images whose
+copyright does not allow redistribution; the bug tracker is a public
+resource and attachments are visible to everyone.
+
+Feature requests
+----------------
+
+Librsvg aims to be a small and relatively simple SVG rendering
+library.  Currently we do not plan to support scripting, animation, or
+interactive features like mouse events on SVG elements.
+
+However, we *do* aim go provide good support for SVG's graphical
+features.  You can request new features by filing a bug report as
+noted above.
+
+It is especially helpful if you file bug for a feature request along
+with a sample SVG file that requires it, for example, a file that uses
+an SVG element or CSS property that librsvg does not yet support.
+
+
+Obtaining debug logs
+--------------------
+
+Librsvg can be asked to output debug logs.  Set the ``RSVG_LOG``
+environment variable, and then librsvg will print some 
+information to stdout:
+
+.. code-block::
+
+   $ RSVG_LOG=1 some-program-that-uses-librsvg
+   ... debug output goes here ...
+
+As of librsvg 2.43.5, there are no options you can set in the
+``RSVG_LOG`` variable; the library just checks whether that environment
+variable is present or not.
+
+Security bugs
+-------------
+
+For especially sensitive bugs, please see :doc:`security`.
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 856a3920..097fb514 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -10,6 +10,7 @@ Development guide for librsvg
    roadmap
    compiling
    security
+   bugs
 
 .. toctree::
    :caption: Getting Started as a Contributor
@@ -64,6 +65,7 @@ evolved into a few different tools.
 - :doc:`compiling` - Cross compilation, debug/release builds, special options.
 - :doc:`security` - Reporting security bugs, releases with security
   fixes, security of dependencies.
+- :doc:`bugs`
 
 Getting started
 ---------------