$wgGroupPermissions['user']['read'] = true; $wgGroupPermissions['*']['read'] = true; How to Report a Bug - Forge Wiki
SCM

How to Report a Bug

From Forge Wiki

Jump to: navigation, search

Reporting bugs is a valuable contribution to CamiTK.

However, to write helpful bug reports and thus help the whole CamiTK community, some guidelines should be carefully followed. Indeed, a bad bug report containing not enough information may be at best totally useless, or worst, would make CamiTK developers spend too much precious coding time on triaging bug reports.

This is why you must follow this guideline to report a bug on CamiTK.

Any bug report not following these instructions may be closed with the reason NOT ENOUGH INFORMATION and without any further process.

Contents

Information to Collect Before Submitting a Bug

Check that your bug is not already discussed on the Forum

First of all, you may check the already being discussed bugs on the forum, to see if yours is not already addressed there.

If you are new to reporting bugs here or elsewhere, you may want to try getting help from the more experienced contributors or first ask your question on the Forum.

You might also find this two articles of interest:

Check CamiTK version and installation settings

Use the camitk-config application to get information about your installed version of CamiTK

On Linux

  • On a terminal and type:
camitk-config --config

From CamiTK 3.5, you can simply use the --bug-report-info option of camitk-config to generate a bug report template, or click on "Report Bug" in the "Help -> About" camitk-imp dialog. From the command line:

camitk-config --bug-report-info


On Windows

  • Open a command shell (Start->search->cmd)
  • Go to the directory where CamiTK is installed, which is generally
cd C:\dev\CamiTK\install\bin
  • Run the camitk-config program with the --config option
camitk-config.exe --config

On Mac OSX

  • Open a terminal
  • run the following command (you may have to use the absolute path to camitk-config if you did not install CamiTK in /usr/local/bin or any other default paths).
camitk-config.exe --config

On all Systems

The results of camitk-config command is very instructive. With it you can:

  • Check that your directories are correctly set.
  • Check that all the application-action (i.e., the action of the application family) can be loaded
  • Copy the resulting text to paste it within your bug report if none of the above check pointed you to a regular installation problem

Where to report?

There is one main bug tracker for CamiTK: BugZilla.

But if you think that the issue is linked with the debian packaging, then the best is to use the CamiTK Debian package tracking system.

Check that your bug has not already been reported

Once your are logged in BugZilla, you can search bugs (menu Search) with keywords. Make sure that your bug is not already filed.

Note that when typing your bug title, BugZilla will automatically search for any already submitted bug. Pay attention to the search results, it is not rare to have the same bug as someone else.

If the bug is already reported, check what the description and read the related discussion. If there is some variation on what you observes on your configuration (OS, CamiTK version, anything else), please post your additional information. That might help us. Knowing that the bug was encountered by more than one person is also of high relevance.

Find out which product is concerned

Make sure you made everything possible on your side to isolate the bug to something due to CamiTK itself and not your own extension/CEP. If you need help on how your own extension links to CamiTK, please consider asking on the forum.

While filing a bug on our site, you will first be asked to pick a product among

  • Actions
  • Applications
  • Components
  • Core
  • Feature requests
  • Installation/Package
  • Libraries
  • Python
  • Other

Please try to narrow down the source of the bug.

If you use CamiTK Developer version, try to use the debugger to find out the name of the file responsible for the bug.

While Reporting a Bug

Focus on One Issue

Only report one issue per bug report. Do not provide multiple issues within one report. CamiTK team will use the bug report id to follow up the bug correction process (related commit on svn, documentation, etc) which becomes extremely difficult if a single report concerns several problems. Bug solving is fasten if the bug report is well focused.

The next section gives you the list of things that are absolutely mandatory to provide in a bug report.

Note that since CamiTK 3.5, you can use camitk-config command to generate this pattern with all configuration informations included. For that, use the --bug-report-info option (or use -b) of the "camitk-config" command, in a console at the camitk/bin directory, and copy/paste the output in your bug description. You can also click on "Report Bug" in the "Help -> About" dialog of Camitk-imp to generate a bug report template. See also the explanation about the bug report template below.

From CamiTK 3.5, using the command line:

camitk-config --bug-report-info

Or click on "Report Bug" in the "Help -> About" dialog of Camitk-imp to generate a bug report template.

General Information

Product

Please refer to the previous section.

Version

The best would be to report only the bug related to the latest svn version. However, whatever your version is, we will not be able to fix a bug if we do not know which installation process/which version you used (stable or svn).

Hardware

Please specify in the hardware section PC or other (and detail other things in the description)

OS

Please specify your OS here. The more specific you get, the better (e.g., Windows 7 64bits). On linux, for instance, please specify the distribution name and the result of the command "uname -a".

Summary

The goal of the summary is to allow CamiTK developers to rapidly sort and affect bug to be fixed. It should be a short sentence summing up the important points of the bug, for example,

The CamiTK-Imp application crashes when X-action is applied on Y-component 
    with parameters the a=1, b=4 and c=25.3

A summary simply telling:

CamiTK doesn't work

is not enough, as we do not know:

  • what application does not work ?
  • what does not work (compilation, execution, action application, component opening, etc.) ?
  • when does not it work (on a certain component opening, on each File->Open call, etc. ) ?

Imagine a CamiTK developer who wants to know if (s)he is capable of fixing this bug... Does your summary help her/him ?

Description Outline

The Description section should follow this outline:

  • overview
  • CamiTK version
  • Steps to reproduce


From CamiTK 3.5, you can simply use the --bug-report-info option of camitk-config to generate a bug report template:

camitk-config --bug-report-info

Or click on "Report Bug" in the "Help -> About" dialog of Camitk-imp to generate a bug report template.

Overview

You should rewrite here a larger and more detailed restatement of your summary.

CamiTK Version

Print the result of camitk-config --config at least up until the list of registered components and actions. Add the registered components and actions if they help understanding your bug.

Steps to Reproduce

Most of the time, it is unclear what is causing a bug/problem. Thus, to fix a bug, CamiTK team needs to reproduce the exact steps that lead to it. You should not only describe the environment on which the bug happened, but also what were the precise steps are performed to reproduce it. Even better, if you compiled CamiTK in debug mode, you may additionally write the debugger stack trace and the name and line of the file where the bug occurs (the code line number makes sense only if you specify the exact svn version of CamiTK you are using).

A one-time bug is not reproducible, it cannot be fixed.

If you cannot write a detailed step-by-step to reproduce a bug, and cannot characterize it, consider holding off on filing a bug report until you have a better understanding and can describe it more specifically.

Actual Results vs Expected Results

You should write in this section what you obtained when you follow the step-by-step given at the previous paragraph. For this, you should use

  • textual description
  • copy/paste of the error message
  • screenshot of the result (as an attachment to your bug report)

To really understand your bug and help fixing it, you may also provide what result you expected and in what aspect the result you obtained is different from the one you expected.

In this section, you should be as objective and as factual as possible.

Possible Interpretation

Your interpretation of where the bug may come from is very welcome and would be of great help for CamiTK team to solve it. However be careful to write it separately from the factual previous information to not confuse the message.

Bug Report Description Overview Template

You may copy/paste and fill-in/replace the following text template in your bug report description:

About you:
[Present yourself and your project you're working on with CamiTK]
 
Overview:
[Rewrite here a larger and more detailed restatement of your summary]
 
CamiTK Version
[Print the result of camitk-config --config]
 
Steps to Reproduce
[Write here the step-by-step process to reproduce the bug, including file to test (you can attach file on BugZilla / the forum)]
 
Actual VS Expected Result
[Write here the result of the step-by-step process and explain why it is not what you expected]
 
Interpretation
[Write here your interpretation of this bug]

Attachment

You may want to attach a screenshot of the error message obtained, as well as input data which lead to the bug.

After Bug Submission

Be available to give feedback if needed

Do not submit a bug if you are not really willing for it to be fixed.

Filing a bug will start the process of finding out how critical it is (which in itself takes time of our limited resources) and how to solve it. By submitting a bug, you thus commit yourself to follow up this submission and answer the questions asked by anyone about this bug. If you are not willing to contribute in that way, please do not submit reports as it will be generating useless workload.

Keep Calm and Carry On

Bugs can be frustrating, especially when it feels like CamiTK team is not fixing it fast enough. Our human resources are limited but competent and motivated, so do not give up and be patient. Keep cool. Ranting can be quite unproductive, and just makes you look bad for all posterity (internet is forever). Instead keep discussions civil and polite. A little thanks and polite messages here and there would also be appreciated.

Thank you for contributing to CamiTK high level of quality !

Sources and References

This description has been inspired by the following posts:

Powered By FusionForge