Changes between Version 5 and Version 6 of BugReporting

Timestamp:

Feb 20, 2016, 11:58:23 PM (8 years ago)

Author:

Ryan J Ollos

Comment:

Rewrite to clarify and remove out-dated info (e.g. about WebAdmin, which is included in Trac since 0.11).

BugReporting

@@ -3 +3 @@
 = How to Report Bugs
 
-If you find a bug in a plugin and you would like the author or maintainer to know about it, you should collect some useful information before creating a [/newticket new ticket]. You can use this link where you correctly fill in "Component" and "Assigned To" fields to make a ticket, but it is better to use the direct links at plugins' home pages.
+If you find a bug in a plugin that you would like to report, you should collect some useful information before creating a ticket. You can use [/newticket this link] or the //New Ticket// link on the main navigation provided you properly select the ticket //Component//, but if you are unsure it is better to use the link on the plugin's home page. Search for existing tickets before creating a new one.
 
-== Describing Bug
+== Describing the Bug
 
-First of all you should find out how your bug can be replicated. Sometimes it's obvious, but sometimes it requires a specific succession of steps and a specific system configuration. Writing a few sentences about that will help a lot. If you are unable to replicate your bug, make a ticket anyway, but make a note about that.
+You should first discover a repeatable sequence of steps to replicate the defect. Writing a few sentences will be very helpful. If you are unable to replicate your bug, make a ticket anyway, and just provide as much information as possible.
 
 == Collecting Debug Messages
 
-Plugins should use debug messages logged to file to help determining where the problem occurs. If your bug is not only functional, but it is provided by error message or traceback, you should collect the debug messages too. There are two ways to enable logging on debug level.
+Plugins should use debug messages logged to file to help determine where the problem occurs. If your bug is not only functional, but also accompanied by an error message or traceback, you should collect the debug messages after configuring the logger.
 
-First, the hard one, is described at [t:TracLogging]. For our purposes it is needed to set these variables in your `trac.ini` configuration file:
+The logger is configured by editing your `trac.ini` configuration file:
 
 {{{#!ini
@@ -21 +21 @@
 }}}
 
-The second one is easier but you have to have had WebAdminPlugin installed. Just go to "Admin" section and "Logging" page and set there "Type" field to "file" and "Log level" field to "DEBUG".
+Equivalently, you can set those parameters through the Admin Logging page (`/admin/general/logging`). More information can be found on the TracLogging page.
 
-You will probably need to restart your web server after changing that in both cases. Then replicate your bug again go to "<trac_environment_path>/log/" folder and open log file named trac.log (by default). There collect any lines near the error message that you think are relevant or few tens if you are not sure about that and post them in the ticket. Don't forget to enclose these lines in triple brackets (!{{{ }}}) when pasting the content into a ticket.
+After replicating your bug again, go to the `$env/log` directory and open the log file, which by default is named `trac.log`. Collect any lines near the error message that you think are relevant and post them in the ticket. The log lines should be enclosed in triple brackets (`{{{ }}}`) when pasting the content into a ticket. If your log content is particularly lengthy you should instead attach the log file to the ticket.
 
 == Describing Your System
 
-Many bugs are platform dependent, so you should sumarize your system information in the begining of the ticket. Relevant is your exact Trac version (0.10.3, SVN trunk r3500, ...), the web server you are running Trac at (Apache+CGI, Apache+mod_python, tracd, ...), database backend (sqlite, PostgreSQL, MySQL, ...), database bindings (pysqlite, ...), operating system (Windows, Linux, MacOS, ...) and of course the plugin's version. Example:
+Many bugs are platform dependent, so you should sumarize your system information in the begining of the ticket. Relevant is your exact Trac version (0.10.3, SVN trunk r3500, ...), the web server you are serving Trac through (Apache+CGI, Apache+mod_python, tracd, ...), the database backend (sqlite, PostgreSQL, MySQL, ...), database bindings (pysqlite, ...), operating system (Windows, Linux, MacOS, ...) and of course the plugin's version.
 
+Example:
 {{{
 DiscussionPlugin: 0.10 (r1941)
@@ -37 +38 @@
 }}}
 
-Not all information is needed in all cases, but if you are not sure, it's better to put all of it in the ticket.
+The information can be found on the //About Trac// page (`/about`). You should also include any plugin-specific configuration that you've added to `trac.ini`.