##(see the SpecSpec for an explanation)

''Please check the status of this specification in Launchpad before editing it.  If it is Approved, contact the Assignee or another knowledgeable person before making changes.''

 * '''Launchpad Entry''': UbuntuSpec:apport-better-retracing
 * '''Packages affected''': `apport`

== Summary ==

Currently, the apport retracing bot produces poor results very often. This specification identifies common cases and describes how to make the bot work for those as well.

== Rationale ==

Manually retracing crash reports takes a lot of time and effort; developer brain and time is much better spent on fixing bugs. Ideally, the retracing bot should be able to cope with all crash reports and turn them into useful information.

== Failure Cases ==

 0. Dynamically loaded libraries (themes, plugins) which are in `/proc/pid/maps`, but are not in the set of transitive dependencies of the affected package
 
 0. The crash happened with old versions of the affected package and/or dependencies.

 0. Broken `CoreDump.gz` attachments (zlib errors out).

 0. `StacktraceTop` is cluttered with crash irrelevant functions such as `abort()`. This reduces information for people looking at it and also impairs the precision of automatic duplicate detection (which primarily works on this field).

 0. Retraced stack trace is sometimes difficult to examine for upstreams if we patch the source and the source line numbers change.

 0. Useless stack traces for Wine. (This also applies to Mono, but that has its own spec: UbuntuSpec:apport-mono-crashes).

== Implementation ==

 0. After installing all transitive dependencies, `apport-retrace` looks at all files in the recorded `ProcMaps` field of the report. For nonexisting files it uses the current `Contents.gz` to map them to packages, and installs those packages along with their debug symbols.

 0. With automatic `needs-retrace` tagging of filed crash bugs there will be no long delay between filing and retracing the bug any more. The client side should not report a bug in the first place if the installed version is older than the available version in the apt cache.

 0. Most probably these come from partial uploads, since the current system does not recognize them. Apport needs to determine the size of the upload and set the HTTP `ContentLength` parameter to make LP reject partial uploads.

 0. We need to collect a set of common crash handlers of applications, glibc functions, etc. and create patterns from them. `StacktraceTop` is unwound until none of the pattern matches any more.

 0. Convoluted local variable values and source lines are too confusing, so we will generate another attachment `StacktraceCode` with the affected source lines and 4 lines of context. To do this, the retracer will fetch the source package and try to apply patches on a best-effort basis with

  {{{
 debian/rules setup || debian/rules patch || debian/rules apply-patches || 
 debian/rules apply-dpatches || debian/rules unpack || debian/rules patch-stamp }}}

 0. Upstream refuses our stacktraces and encourages us to use winedb instead. The Ubuntu wine maintainers and MartinPitt will work together to design a package hook that uses winedb for post-mortem analysis. As a fallback plan, the hook should set `UnreportableReason` to avoid reporting useless traces.

----
CategorySpec