Submit an issue or report a bug

How to submit an issue.

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 bug reports triage.

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

Any bug report that does not follow these instructions might not be properly taken into account!

Information to collect before submitting a bug or an issue

Check that your bug is not already discussed on the issue board

First of all, you may check the already being discussed bugs, 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 How to ask for help. You might also find this two articles of interest:

You can use your bug search keywords here:

Search an open CamiTK issues

Check CamiTK version and installation settings

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

In a terminal (bash, git bash, console, cmd)

Just type:

camitk-config --config

You can simply use the --bug-report-info option of camitk-config to generate a bug report template.

From the command line:

camitk-config --bug-report-info

If camitk-config is not in your system PATH you will need to open the terminal in the extension repositories where it is installed (or cd to this directory).

For instance, if camitk-config is located in C:\camitk-dev\install\bin, you need to run camitk-config from C:\camitk-dev\install.

From camitk-imp

Launch camitk-imp, open the “Help → About” menu and click on the “Report Bug” button in the help dialog.

Note about camitk-config

The results of camitk-config command is very instructive.

With it you can:

  • Check that your directories are correctly set.
  • Check what are the different extension repositories on your machine.
  • 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 board for CamiTK: the gitlab issues tracking system.

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 (but don’t worry, if you don’t know just go to the gitlab issue tracking system first.).

When to report?

Once your are logged in the issues tracking system, you can search bugs (see screenshot below) with some keywords. Make sure that your bug is not already filed:

Search issue

If the bug is already reported, check 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.

Reporting a bug

Use an issue description template

When you submit a new issue, you will see that we defined three specific templates :

  • a template to submit a bug
  • a template to submit a feature
  • a template to submit a technical feature

Please use the one that looks the most appropriate for your issue!

Find out which application/library 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 or a third-party library. If you need help on how your own extension links to CamiTK, please consider How to ask for help.

If you use CamiTK Developer version, try to use the debugger to find out the name of the file responsible for the 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 Git, 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.

Fields to fill in

About you

Please give us some light details about you.

Overview

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 a=1, b=4 and c=25.3

If you write:

CamiTK doesn’t work

this is not enough!

We need to know more to help you:

  • what application does not work ?
  • what does not work exactly (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 ?

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 VS Expected Result

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

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.

Relevant logs and/or screenshots

For this, you may use:

  • textual description
  • copy/paste of the error message or log
  • screenshots of the result

To attach a file just click on the Attach a file link on the bottom right of the description field.

Interpretation & Possible fixes

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.

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.

Please do not remove the tag quick actions such as /label ~Bug that appears at the bottom of the generated report ore issue template. This little snippets add a tag in the issue board that help us do the bug triage.

After the bug or issue submission

After the bug or issue submission, please stay available to give feedback if needed or to answer the questions that may arise from your submission

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.

Thank you for contributing to CamiTK project quality!

Sources and references

This description has been inspired by the following posts: