Debian Codegraph @

doc/README.developers

raw
1 ===================================
2 reportbug's Features for Developers
3 ===================================
4
5 (Adapted from original "bug" documentation.)
6
7 Bug allows maintainers to control the bug reporting process by placing
8 files in special places.
9
10 Template Information & Interaction with the user
11 ================================================
12
13 If /usr/share/bug/$package is executable, then bug executes it and
14 takes what comes out from the file descriptor 3 and puts it in the bug
15 template.
16
17 The maintainer can then ask questions to the user or run whatever
18 information gathering script he likes, and echo all the content to fd 3.
19
20 e.g.::
21
22 read -p 'color? '
23 echo "Color: $REPLY" >&3
24 ...
25 system-information-tool >&3
26
27 If /usr/share/bug/$package is a directory, then
28 /usr/share/bug/$package/script is executed.
29
30 While the script is executed, the following shell functions are
31 available ONLY IF IT IS RUN UNDER /bin/bash::
32
33 getkey - asks for a key
34 yesno <prompt> "yep"|"nop" - ask for a yes/no answer (with i18n)
35 leaves response as yep or nop
36 in REPLY. The second argument is
37 the default.
38
39 If the file /usr/share/bug/$package/presubj exists, its content is
40 shown to the user before asking him for the bug's subject.
41
42 Note: It's your responsibility to check if the information included
43 in the template can put the user in any security risk.
44
45 Package redirection
46 ===================
47
48 The package maintainer can control to which packages bug reports are
49 submitted, by setting the Package: field of the bug report. This will
50 be mainly used to redirect bugs in packages coming from a single
51 source to where the maintainer likes to have them.
52
53 This is done by having this line in /usr/share/bug/$package/control::
54
55 Submit-As: $new-package
56
57 Note that bug will not check if the $new-package exists as a valid package.
58
59 BTS selection
60 =============
61
62 Packages not distributed by Debian can take advantage of this utility too.
63 They just need to add a "send-to" header to the control file
64 /usr/share/bug/$package/control::
65
66 Send-To: bugs.myproject.com
67
68 ``reportbug`` will add ``submit@` ``quiet@`` or ``maintonly@`` to form the address the
69 bug report mail is send to.
70
71 (Note: you probably should use dpkg's support for Origin and Bugs tags
72 in lieu of this support.)
73
74 Nicolás Lichtmaier.-
75 [email protected]
76
77 Related packages
78 ================
79
80 Often programs are distributed across several different packages, for
81 example an upstream package 'foo' may be packaged in Debian as foo, libfoo,
82 foo-common and foo-data. In such cases it can be useful to include related
83 package information in bugreports, to minimise the need for 'moreinfo' requests
84 to the submitter :) This is done by adding a "report-with" header to the
85 control file::
86
87 report-with: foo libfoo foo-common foo-data
88
89 Package information will be added to the bug report for each extra package
90 listed.
91
92 You can also request that the status information for other packages
93 (that are not dependencies or recommendations) be included with the
94 report using the "package-status" header::
95
96 package-status: bar baz
97
98 Addendum: Languages other than SH
99 =================================
100
101 The script in /usr/share/bug/reportbug/script is an example of a bug
102 handling script written in Python. You can also write bug handlers in
103 many other languages that allow direct access to file descriptors,
104 including Perl and C/C++.
105
106 Note that the getkey and yesno functions are only available in scripts
107 written using /bin/bash as their interpreter; for other shells or
108 languages, you will need to write your own input parsing functions.
109
110 Add Headers and Pseudo-Headers from the bugscript
111 =================================================
112
113 From the bugscript it's possible to extend the bug report with additional (mail)
114 headers and (bug) pseudo-headers. They need to be enclosed in a begin/end block:
115
116 -- BEGIN HEADERS --
117 ...
118 -- END HEADERS --
119
120 for mail headers, and:
121
122 -- BEGIN PSEUDOHEADERS --
123 ...
124 -- END PSEUDOHEADERS --
125
126 for bug pseudo-headers.
127
128 They can be emitted in any place of the output (they will be removed during
129 parsing), can be repeated several times, and support several headers in the same
130 block:
131
132 -- BEGIN PSEUDOHEADERS --
133 User: [email protected]
134 Usertags: dd
135 -- END PSEUDOHEADERS --
136
137 will correctly identify the two pseudo-headers (as needed for usertagging a
138 report).
139
140 Please pay attention to not interleave blocks with each other and to always
141 close blocks, else the parser could produce undesired results. Also note that
142 those headers are added to the ones already presente so a header with the same
143 name will appear twice, since it won't replace the existing one.
144
145 Bugscripts and locale information
146 =================================
147
148 Please be aware that reportbug runs every bugscript in a shell forcing
149 `LC_ALL=C`, this is to prevent the commands output in the script to be
150 unintelligible when sent via email.
151
152 Part of reportbug "System Information" section of a bug template, already
153 contains the locale information, no need for your bugscript to re-discover that
154 information again.
155
156 Add attachments from the bugscript
157 ==================================
158
159 Similarly to headers and pseudo-headers, it's possible to add an attachment
160 from the bugscript using this syntax:
161
162 -- BEGIN ATTACHMENTS --
163 /path/to/the/file/to/attach
164 -- END ATTACHMENTS --
165
166 and that will attach the mentioned files to the bug report (if that's allowed,
167 in particular with not using a MUA but the internal reportbug mail facility).
168
169 Source layout
170 =============
171
172 The source tree for ``reportbug`` is organised this way:
173
174 * Top level
175
176 * Programs (e.g. ``reportbug``, ``querybts``, etc.).
177
178 * Python library modules, used by the programs.
179
180 * Manual pages.
181
182 * Debian packaging
183
184 * ``debian/`` contains the control files used to build the Debian
185 source and binary packages.
186
187 * `Unit testing framework`_
188
189 * ``test/`` contains the unit test suite. Unit test modules are
190 discovered and run using the ``pytest`` program, and are named as
191 ``test_*.py``.
192
193 * ?? TODO: describe the purpose
194
195 * ``checks/`` contains ???
196
197 * Internationalisation and localisation
198
199 * ``po4a/`` contains configuration and data for localisation of
200 source files using the ``po4a`` tool.
201
202 Unit testing framework
203 ======================
204
205 The reportbug source package now has a unit testing framework.
206
207 The directory ``test/`` contains unit test modules and supporting
208 files. New unit test modules should be added to this directory and
209 named ``test_*.py``.
210
211 The unit test suite depends on the `python3-pytest` and `python3-pytest-cov`
212 package being installed, to make the ``pytest`` command available. The unit
213 tests themselves can be written using either the `unittest` or `doctest`
214 modules in the standard Python library.
215
216 The `scaffold` module (from the ``test/scaffold.py`` file) contains
217 some helper functionality for unit tests, including an extended
218 `TestCase` class.
219
220 ``make`` targets for testing and quality checks
221 -----------------------------------------------
222
223 The following ``make`` targets are useful for testing and related
224 tasks.
225
226 * ``make test`` runs the unit test suite, preceded by a timestamp
227 banner, and reports any test failures or "OK" if all tests pass. Coverage
228 reports are generated automatically.
229
230 * ``make test-continuous`` starts a loop which clears the screen, runs
231 ``make test``, then waits for any of the tests or source code to
232 change, and starts the loop again.
233
234 This is useful to run in a separate terminal during a development
235 session, so that whenever a change is made the test suite will be
236 run automatically. You might want to keep the window hidden while
237 actually editing files, and only look at it when you've created or
238 modified a file and want to check its effect on the test run.
239
240 This uses the ``inotifywait`` command from the `inotify-tools`
241 package to wait for `create` and `modify` events.
242
243 * ``make lint`` runs the `flake8` code checker on all code modules and
244 programs.
245
246 This requires the `flake8` package to be installed. See its
247 documentation for more about its operation.
248
249
250 ..
251 Local Variables:
252 coding: utf-8
253 mode: rst
254 End:
255 vim: filetype=rst :