= How to Submit a Ticket =

[[TOC]]

=== Historical Note ===
In the old SourceForge tracker we had ''Bugs'', ''Patches'' and ''Feature Requests''.
Now we have ''tickets''. If you have ever used wx SF tracker, please read [wiki:WikiStart] to learn how to use the same username.

=== Introduction ===
Before creating a new ticket, '''you must login'''. __Make sure that the e-mail address in your preferences is correct.__

Please '''search''' if the bug or proposed enhancement is already submitted (use [/search?ticket=on search] for global search or queries to list tickets with the classname in [query:status!=closed&summary~=listctrl title] or [query:status!=closed&keywords~=wxListCtrl keyword]) before reporting it. If you are not sure that you encountered the same bug, please open a new ticket and add mutual links to both tickets (`#1234` is automatically linked). 

If you want to express interest in a bug that is already submitted, CC yourself or add more details. Or even better, try to fix it.

When reporting a bug, it's usually obvious to the submitter (you) what the problem is. Unfortunately it's quite often less obvious to us (the developers) and the chances of a bug being fixed decrease dramatically if we can't even understand what it is. So please follow this general template when reporting the bugs, with the possible exception of really trivial and self-explanatory ones:

 1. Describe what you do, ideally provide a patch to a sample doing it
 2. Describe what you expect to happen
 3. Describe what happens

Variations are possible, of course, but please follow the above steps if in doubt. Also see the descriptions of the individual fields below for more details.

=== Summary ===
Like in [https://wiki.ubuntu.com/X/Reporting#head-63f6d4e3e78a5db3d861bc10bdceab01d8c9ad8d other] issue trackers you should select a meaningful title. You may assume that the `summary` will be viewed together with `type` and `component`, so you don't need to write `[wxMac]` if the component is set to `wxMac`.

=== Component ===
`Component` is the most important drop-down field. 

If the ticket is related to `wxHtml*`, `wxAui*`, `wxRichText*`, `wxStyledText*`, `wxGrid` or `OpenGL`, use these names as a component, but remember to write what wxPort and OS are you using.

If you see a bug in the control that has generic implementation on your platform, select `GUI-generic`. `wxTreeCtrl` has generic implementation on all platforms but MSW. `wxFileCtrl` has native implementation only on GTK. When in doubt, look it up in a header file.

If the bug is in the `base` sub-library (see [/browser/wxWidgets/trunk/build/bakefiles/files.bkl files.bkl] to find out which files belong there), select `base`.

If the ticket is relevant to more than one port (and it's neither `base` nor `generic`), select `GUI-all`.

`wxPython` is for Python-specific issues and for C++ classes that are in wxPython but not in wxWidgets.

`build` is for ticket related to bakefiles, `configure.in`, `wx-config`, etc.

You can probably guess when to use other options.

=== Keywords ===
Use full C++ names of relevant classes as keywords (e.g. `wxFileDialog`, not ~~`file dialog`~~ nor ~~`FileDialog`~~).

If your platform is not very popular, add it also as a keyword (e.g. Solaris, IRIX, Win9x).

Other suggested keywords are: 
  * `printing`, 
  * `dnd` (for drag'n'drop problems), 
  * `transparency` (for alpha-channel problems),
  * `thread` (for concurrency problems, if wxThread is not given),
  * `regression`.

=== Version and Milestone ===
Please set the `version` field but don't set the `milestone`, this field is meant to be used by developers and setting it doesn't help with fixing the bug sooner.

=== CC ===
In the current Trac configuration, reporter is always notified about ticket changes, so there is no need to add yourself to the ''cc'' list. Use this field when you are interested in a ticket opened by someone else.

=== Description ===

Explain how to reproduce the problem. Check if you can see it in the samples. If not, try to make a '''minimal''' modification to one of the samples to demonstrate it and attach this modification as a patch ([http://en.wikipedia.org/wiki/Diff#Unified_format unified] format with extension .diff or .patch is preferred). If the patch only demonstrates the bug, don't check the patch checkbox. You can also attach a minimal complete application in a single `.cpp` file.

If you use wxPython and can show the program in a few lines of Python code, that's also useful. Make sure the code is '''complete''' (with imports and instantiation of `wx.PySimpleApp()`) 
and '''minimal'''.

''Minimal'' means that every line of the code is necessary.

Write what platform you are using. If you tested also other platforms or older versions, let us know.

=== Patch ===
Attaching a patch that fixes the bug or implements the enhancement you propose will give a higher priority to your ticket. Please read [wiki:HowToSubmitPatches] for the details.

=== Things To Do To Dissuade Us From Fixing a Bug ===
Following the guidelines in this page helps a lot with fixing the bug but unfortunately it doesn't always ensure that it is fixed (unless you also submit a patch), unfortunately. However there are several things which you can do which might not ensure that the bug is ''not'' fixed, strictly speaking, but which come pretty close. Here are some examples:

 * Not providing enough details about the problem.
 * Opening multiple identical (or very similar) bug reports about the same problem, usually still without providing enough details.
 * Incrementing the bug priority or moving its target milestone, typically even though it was already reset by a developer before.
 * Putting strongly-worded requests to fix your bug as soon as possible (usually in capital letters) in the summary or description.
 * Trying to generate interest in your problem by insulting wxWidgets developers when the above fails.

Doing anything of the above is just a waste of time so please don't engage in it.

=== Final Note ===
wxWidgets is a community project and we need your help. At the very least, if you see that the bug you reported in the past was fixed, but the ticket is still open, we will appreciate if you close it. You can easily list [query:status!=closed&reporter=$USER&group=component all open bugs you reported].

And, of course, we really welcome other help with the existing bugs: for example, verifying that the bugs can still be reproduced, commenting on potential workarounds and so on.

Thanks in advance!