Writing Bug Reports

A bug report should contain these 4 things:

1. Steps to reproduce: You should give detailed steps on how someone can 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 it is invoked (e.g. say: “Select Cut from the Edit menu”; or, alternatively: “Press ⌘X” rather than “delete the text”)
   • 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 would be OS version, version of TextMate, the language you are working in, and other possibly relevant information. (For example, if you’re seeing graphics artifacts and you’re 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.

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”. These are normally found 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

Adding Pictures

If you include pictures or movies, please make sure the bug report can stand on its own. A report is only useful if it can be understood even without images or movies.

For example: Opening an issue “syntax highlight is incorrect” with nothing besides a screenshot isn’t useful.