README.developers

===================================
reportbug's Features for Developers
===================================

(Adapted from original "bug" documentation.)

Bug allows maintainers to control the bug reporting process by placing
files in special places.

Template Information & Interaction with the user
================================================

If /usr/share/bug/$package is executable, then bug executes it and
takes what comes out from the file descriptor 3 and puts it in the bug
template.

The maintainer can then ask questions to the user or run whatever
information gathering script he likes, and echo all the content to fd 3.

e.g.::

	read -p 'color? '
	echo "Color: $REPLY" >&3
	...
	system-information-tool >&3

If /usr/share/bug/$package is a directory, then
/usr/share/bug/$package/script is executed.

While the script is executed, the following shell functions are
available ONLY IF IT IS RUN UNDER /bin/bash::

	getkey				- asks for a key
	yesno <prompt> "yep"|"nop"	- ask for a yes/no answer (with i18n)
					  leaves response as yep or nop
					  in REPLY. The second argument is
					  the default.

If the file /usr/share/bug/$package/presubj exists, its content is
shown to the user before asking him for the bug's subject.

Note: It's your responsibility to check if the information included
in the template can put the user in any security risk.

Package redirection
===================

The package maintainer can control to which packages bug reports are
submitted, by setting the Package: field of the bug report.  This will
be mainly used to redirect bugs in packages coming from a single
source to where the maintainer likes to have them.

This is done by having this line in /usr/share/bug/$package/control::

	Submit-As: $new-package

Note that bug will not check if the $new-package exists as a valid package.

BTS selection
=============

Packages not distributed by Debian can take advantage of this utility too.
They just need to add a "send-to" header to the control file
/usr/share/bug/$package/control::

	Send-To: bugs.myproject.com

``reportbug`` will add ``submit@` ``quiet@`` or ``maintonly@`` to form the address the
bug report mail is send to.

(Note: you probably should use dpkg's support for Origin and Bugs tags
in lieu of this support.)

Nicolás Lichtmaier.-
nick@debian.org

Related packages
================

Often programs are distributed across several different packages, for
example an upstream package 'foo' may be packaged in Debian as foo, libfoo,
foo-common and foo-data.  In such cases it can be useful to include related
package information in bugreports, to minimise the need for 'moreinfo' requests
to the submitter :) This is done by adding a "report-with" header to the
control file::

        report-with: foo libfoo foo-common foo-data

Package information will be added to the bug report for each extra package
listed.

You can also request that the status information for other packages
(that are not dependencies or recommendations) be included with the
report using the "package-status" header::

        package-status: bar baz

Addendum: Languages other than SH
=================================

The script in /usr/share/bug/reportbug/script is an example of a bug
handling script written in Python.  You can also write bug handlers in
many other languages that allow direct access to file descriptors,
including Perl and C/C++.

Note that the getkey and yesno functions are only available in scripts
written using /bin/bash as their interpreter; for other shells or
languages, you will need to write your own input parsing functions.

Add Headers and Pseudo-Headers from the bugscript
=================================================

From the bugscript it's possible to extend the bug report with additional (mail)
headers and (bug) pseudo-headers. They need to be enclosed in a begin/end block:

    -- BEGIN HEADERS --
    ...
    -- END HEADERS --

for mail headers, and:

    -- BEGIN PSEUDOHEADERS --
    ...
    -- END PSEUDOHEADERS --

for bug pseudo-headers.

They can be emitted in any place of the output (they will be removed during
parsing), can be repeated several times, and support several headers in the same
block:

    -- BEGIN PSEUDOHEADERS --
    User: morph@debian.org
    Usertags: dd
    -- END PSEUDOHEADERS --

will correctly identify the two pseudo-headers (as needed for usertagging a
report).

Please pay attention to not interleave blocks with each other and to always
close blocks, else the parser could produce undesired results. Also note that
those headers are added to the ones already presente so a header with the same
name will appear twice, since it won't replace the existing one.

Bugscripts and locale information
=================================

Please be aware that reportbug runs every bugscript in a shell forcing
`LC_ALL=C`, this is to prevent the commands output in the script to be
unintelligible when sent via email.

Part of reportbug "System Information" section of a bug template, already
contains the locale information, no need for your bugscript to re-discover that
information again.

Add attachments from the bugscript
==================================

Similarly to headers and pseudo-headers, it's possible to add an attachment
from the bugscript using this syntax:

    -- BEGIN ATTACHMENTS --
    /path/to/the/file/to/attach
    -- END ATTACHMENTS --

and that will attach the mentioned files to the bug report (if that's allowed,
in particular with not using a MUA but the internal reportbug mail facility).

Source layout
=============

The source tree for ``reportbug`` is organised this way:

* Top level

  * Programs (e.g. ``reportbug``, ``querybts``, etc.).

  * Python library modules, used by the programs.

  * Manual pages.

* Debian packaging

  * ``debian/`` contains the control files used to build the Debian
    source and binary packages.

* `Unit testing framework`_

  * ``test/`` contains the unit test suite. Unit test modules are
    discovered and run using the ``pytest`` program, and are named as
    ``test_*.py``.

* ?? TODO: describe the purpose

  * ``checks/`` contains ???

* Internationalisation and localisation

  * ``po4a/`` contains configuration and data for localisation of
    source files using the ``po4a`` tool.

Unit testing framework
======================

The reportbug source package now has a unit testing framework.

The directory ``test/`` contains unit test modules and supporting
files. New unit test modules should be added to this directory and
named ``test_*.py``.

The unit test suite depends on the `python3-pytest` and `python3-pytest-cov`
package being installed, to make the ``pytest`` command available. The unit
tests themselves can be written using either the `unittest` or `doctest`
modules in the standard Python library.

The `scaffold` module (from the ``test/scaffold.py`` file) contains
some helper functionality for unit tests, including an extended
`TestCase` class.

``make`` targets for testing and quality checks
-----------------------------------------------

The following ``make`` targets are useful for testing and related
tasks.

* ``make test`` runs the unit test suite, preceded by a timestamp
  banner, and reports any test failures or "OK" if all tests pass. Coverage
  reports are generated automatically.

* ``make test-continuous`` starts a loop which clears the screen, runs
  ``make test``, then waits for any of the tests or source code to
  change, and starts the loop again.

  This is useful to run in a separate terminal during a development
  session, so that whenever a change is made the test suite will be
  run automatically. You might want to keep the window hidden while
  actually editing files, and only look at it when you've created or
  modified a file and want to check its effect on the test run.

  This uses the ``inotifywait`` command from the `inotify-tools`
  package to wait for `create` and `modify` events.

* ``make lint`` runs the `flake8` code checker on all code modules and
  programs.

  This requires the `flake8` package to be installed. See its
  documentation for more about its operation.


..
    Local Variables:
    coding: utf-8
    mode: rst
    End:
    vim: filetype=rst :