Writing Bug Reports

Before reporting a bug try first reverting to defaults

A bug report should contain these 4 things:

1. Steps to reproduce: Give detailed steps on how to reproduce the problem.

   • Start from scratch (e.g. “1. Create a new document, 2. Change language to Ruby, 3. …”).
   • Explicitly mention every action involved, and how you invoked it (e.g., rather than “delete the text”, say “Select Cut from the Edit menu” or “Press ⌘X”).
   • Keep the number of steps to a minimum.

2. Expected result: It’s important to include the result you’re expecting, as it might differ from how the program was designed to work.

3. Actual result: This is also important, since it’s possible that following your steps on a different system doesn’t reproduce the issue.

4. Environment: This includes:

   • OS X version
   • TextMate version
   • the (code) language you’re working in
   • other possibly relevant information (for example, if you’re seeing graphics artifacts on a retina MacBook Pro, you should include that)

Your Bug Report’s Title

See this great article (by Jakob Nielsen) on writing headlines, page titles, and subject lines.

Adding Pictures

As they say, “a picture is worth a thousand words”…but that is not what we want in a succinct bug report! (Not to mention the plethora of other issues related to submitting bug reports as images.)

Only include pictures or movies as extra material, when it clarifies your bug report in ways that cannot be expressed in text. (For example, if text is garbled, it’s useful to include an image of how exactly it gets garbled.)

Opening an issue saying “syntax highlight is incorrect” with nothing besides a screenshot is not acceptable.

Crashes or Hangs

Unless you have steps to reproduce, there’s generally no need to report a crash. We already get crash reports from users who haven’t opted out. (You can change this in Preferences → Software Update.)

Reporting Crashes

If you’re opening an issue about TextMate crashes, please include the corresponding crash report.

You can find a list of submitted reports in Notification Center. Just click the entry to open an online version. This also provides you with a URL to include in the issue (please do!).

You can also find crash reports for your system online under my crashes.

Reporting Hangs

Hangs are different than crashes. If the program locks up, you should find (or create) a “spin report”. Normally, you can find these here:

/Library/Logs/DiagnosticReports/TextMate_«time»_«host».hang

If you need to generate a spin report while TextMate is locked up, here’s how:

1. launch Activity Monitor
2. select TextMate
3. select then Sample Process (⌥⌘S).
4. paste the spin report online via [https://gist.github.com] GitHub’s issues don’t allow file attachments