~bzr-pqm/bzr/bzr.dev

4584.3.5 by Martin Pool
Developer docs on using apport
1
*************************
2
Bazaar Apport Integration
3
*************************
4
5
Bazaar can use Apport <http://launchpad.net/apport/> to capture data about
6
unexpected errors (probably, bugs in Bazaar) and report them to the
7
developers.
8
9
This is only active for errors that are believed to be internal errors (ie
10
bugs) not user or environmental errors.  (See the Developer Guide.)
11
12
Consequences for users
13
----------------------
14
15
* They shouldn't normally need to see or copy&paste a traceback.
16
17
* They will be able to inspect the files before sending them to be sure
18
  there's no sensitive data included.
19
20
* As at present, they'll need a Launchpad account to report bugs in the
21
  normal way.
22
23
24
Implementation notes
25
--------------------
26
27
The use of apport by Bazaar is independent of the configuration in the OS.
28
For example in Ubuntu, apport is normally inactive in release builds, and
29
normally excludes software not installed from a package.  We'll bypass
30
both of them.
31
4584.3.9 by Martin Pool
More apport notes
32
Putting in this handler may mean that an OS-wide exception handler never
33
sees the error, but that was true with our existing exception-printer.
34
4584.3.5 by Martin Pool
Developer docs on using apport
35
The user should have the option to: forget about the crash (and ignore the
4584.3.15 by Martin Pool
More developer docs about apport
36
bug report), see the contents of the report, file a bug, or save the
37
report to file later.  At the moment we just show them the filename and
38
let them take it from there.
4584.3.5 by Martin Pool
Developer docs on using apport
39
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
40
The process is
4584.3.5 by Martin Pool
Developer docs on using apport
41
42
#. An exception reaches the top-level handler.
43
44
#. We log it in apport-format to a file in ~/.bazaar/crash.
45
4584.3.7 by Martin Pool
Updated documentation about apport
46
#. We tell the user where that file is, and invite them to file a bug
47
   report.
4584.3.5 by Martin Pool
Developer docs on using apport
48
49
This won't be active for bugs that cause the whole Python interpreter to
4584.3.12 by Martin Pool
Note on interaction of our handler with system-wide apport
50
crash.  This can be handled at the OS level.  The nice thing is that if
51
apport is active system-wide, it will catch either exceptions in our
52
in-process apport handler, or errors that crash the intrepreter.
4584.3.5 by Martin Pool
Developer docs on using apport
53
54
55
Future ideas
56
------------
57
58
* Capture apport data even for things not believed to be internal errors,
59
  because sometimes they are in fact bugs.  Then the user can attach the
60
  apport report later if they decide to file a bug.  There may be quite a
4584.3.7 by Martin Pool
Updated documentation about apport
61
  lot of them so we might need to limit the number that are stored, or do
62
  this when a debug flag is set.  At the moment they go into .bzr.log and
63
  that's probably ok to start with.
4584.3.5 by Martin Pool
Developer docs on using apport
64
65
* Raising an error from the breakin debugger should cause this to fire.
66
67
* Developers looking at a crash on their own machine will probably in the
68
  first instance just want to see the traceback. Apport files may be more
69
  longwinded than our current output and might make the traceback scroll
70
  off the screen.
71
4584.3.15 by Martin Pool
More developer docs about apport
72
* Automatically trace messages (ie from .bzr.log) in the report.  We could
73
  just include the whole file, but it may be long, and including the whole
74
  thing has a greater risk of including sensitive data.
4584.3.7 by Martin Pool
Updated documentation about apport
75
76
* Ask the user what they want to do with the report: automatically file
77
  it, look at it, see just the traceback, just be told where it is.  This
78
  could be done through the UIFactory so that it can be done through a
79
  graphical dialog.
80
81
  However, if we've already had an unhandled error in this process there
82
  may be problems in Bazaar that prevent us presenting a clean message...
83
84
  Possibly these bugs are better reported in the next time bzr runs.
85
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
86
..
4584.3.5 by Martin Pool
Developer docs on using apport
87
    vim: ft=rst