darktable's Bug Workflow¶
darktable's issues are reported and managed in our own Redmine installation. In order to comment on bugs, update their status, and assign themselves to work on a given bug you have to register and create a user account. darktable Bug Team members can set the bug status to Triaged (more below) and assign priorities.
- Table of contents
- darktable's Bug Workflow
- Please open one issue per request! Do not accumulate your wished or bugs in one issue - this renders a bug tracker useless. The workflow is based on the idea of having one issue per request (either feature or bug) to discuss it further and solve it.
- Please use the search function before you file a new issue. A lot of bugs have already been reported - try to find the issue and append your backtrace. Quite some feature requests have already been discussed elaborately - maybe you find your answers there.
- Have a look at Contributing_Code and the Triager_Guide.
The different trackers¶
Currently we have two trackers, their intended usage is described below:
- Bugs: this tracker collects all issues containing problems with darktable (compilation, use, output images, crashes etc.)
- Features: this tracker is for new feature requests, think of it as a wishlist. But keep in mind: filing a ticket here does not necessarily mean we're going to implement this - it's just you expressing your needs or wishes.
We have the following bug statuses:
- New: this bug was just reported, and it is not known whether it is reproducible. Try to reproduce this bug on your computer.
- Confirmed: this bug was reproduced and verified to be darktable's fault. You can work on tracking it down and fixing it.
- Triaged: a Bug Team member has verified the bug and assigned an importance to it. darktable developers accept that they will work to resolve the bug.
- In Progress: someone is working right now to fix the bug. Do not use this status to indicate that you are willing to work on a given bug, or that you will work on it some time in the future; only set it if you have actually started to work on a fix.
- Incomplete: not enough information was provided by the bug reporter to adequately identify or reproduce the issue. If nobody else encounters a similar problem, it will be marked invalid after some time.
- Patch attached: a bug report with a fix attached should be marked with this status. This makes it easier to keep track of patches supplied via the tracker. A bug can be marked as "Patch attached" if you have created a github pull request solving the issue even if there is no patch attached to the issue directly. Make sure to refer to the correct github pull request.
- Fixed: the bug is fixed in the development version (source:/). If you have committed a fix, but are not sure whether it works, for example if the issue only happens on a platform you don't have access to, leave as "In Progress".
- Fixed: To be cherry-picked: as above: the bug is fixed in the development version but is marked to be picked into the stable patch release branch.
- Closed: Invalid: this problem is not darktable's fault, or the reporter did not reply to requests for more information.
- Closed: Won't Fix: issue that will never be fixed in darktable due to design choices or because it is out of the scope of the program. An example might be a request for file manager abilities in the lighttable mode.
- Closed: Upstream: darktable relies on a number of external libraries such as LibRaw, RawSpeed, Gphoto2. Bugs in those libraries can't be fixed by darktable developers but should be reported upstream to fix them in their projects.
- Duplicate: This bug is a duplicate, the issue has already been reported.
Importance reflects how serious is the bug.
- Critical: very serious incorrect behavior that will severely affect a majority of users. Examples: reproducible crashes after a common action; document data loss; document data corruption; severe regressions in functionality; build broken on more than one platform (Linux, Mac, Solaris, other)
- High: serious incorrect behavior that is likely to affect a large portion of users. Examples: reproducible crash after an uncommon sequence of actions; other user data loss (e.g. preference file corruption); malformed output image; previously supported RAW file misinterpreted; major memory leak; build broken on one platform only
- Medium: moderately serious incorrect behavior that is likely to affect many users. Examples: crash under very obscure or unlikely circumstances; user interface not adhering to standard guidelines; substandard quality of rendering; bad performance; minor memory leak; build issues on exotic but up to date platforms
- Low: quirk or deviation from expected behavior that may affect a small portion of users. Examples: minor rendering quirk; inconvenient placement of commands; inconvenient behavior or limitation of functionality of an existing command; bad performance during obscure operations; incorrect translation; build issues on outdated platforms
Categories relate bugs to a subsystem or general area of functionality of darktable. Currently the following Categories are being used:
- Buildsystem: everything that affects the buildsystem itself (bugs in CMakeLists, wrong library detection on a platform)
- Tethering: all bugs that affect the tethering mode or the tethering functionality of darktable.
- Lighttable: all bugs that occur in the lighttable mode of darktable.
- Darkroom: all bugs related to darkroom actions and modules such as a misbehaving image operator module or the history stack.
- General: all bugs that either can't be categorized by the given tags or that occur in all sections of darktable (such as memory leaks, caching problems, problems with the processing pipe).
darktable is a spare time project. So the development pace relies heavily on the given spare time of the developers. Therefore it does not make sense (and fun) to set up sophisticated roadmaps with due dates and all. Since we want to deliver bug fixes in patch releases as soon as possible we started to deliver them roughly one per month.
This has some implications on the "target version" of a bug or feature:
- Candidate for the next patch release: here we collect bugs and small UI obstacles that affect the current stable version. We want them to be solved and shipped with (one of) the next minor release or patch release.
- Candidate for the next minor release: this target version will later become the next major release of darktable (so basically what we develop right now in the master branch). This target should contain all features and bugs scheduled for this version. This means mostly there is somebody already working on it or at least planning to. Otherwise put it in
- Candidate for the next major release: this will be the next major version of darktable (so currently 2.0) which is far in the future...
- Future: this target version contains all "nice to have" things, so mostly feature requests that might go into darktable somewhen in the future .But nobody is working on them right now and we can't estimate if this task will be finished on a given time scale.
And then we have the numbered target versions. As said above: there is no absolute roadmap, especially not for patch releases. These targets are meant for regressions from a earlier version. So if the current stable version is "1.0.3", the target version "1.0.4" contains /just/ the regressions from the stable version - not all bugs in the version since it's very unlikely to have them fixed all at once. And after releasing "1.0.4" within a reasonable time we would have to move all unfixed bugs again to the next patch target version.
Redmine git integration¶
There are several things that make life easier. If you're working on a bug an you know the issue number you can close the ticket or just reference to the commit you're about to apply. This works as described here:
- Use one of the following referencing keywords in your git commit message to create a cross-reference between the commit and a Redmine issue:
- Use one of the following fixing keywords in your git commit message to close a Redmine issue and set a reference to the commit that fixes the problem:
If you already made a commit and can't change the commit message accordingly or you found an issue that got solved by someone else you can still create a reference or at least a link to the commit. This makes it easier to find relates problems later.
- Use the Redmine text markup for commit references in your issue message: type "commit:HASH" to get a link to the corresponding commit in the repository.
The general methodology for working with bugs is as follows:
Be polite. It takes some effort on the part of the user to come to our site, navigate to the bug report section, and write up a report. If they know their report will be treated seriously and professionally, they'll respect the system and put in extra time to help us solve the issue.
Do not close an unreproducible bug unless a reasonable amount of effort is put into reproducing it, and let it rot for some time before closing -- someone may come up with a better report in comments. (In a few situations we might not be able to recreate the bug, but due to the involved assistance of the user might be able to narrow down and fix the problem, and the user is able to do the validation.)
Clarify. If it took you some time to guess what it's about, change the summary or add a comment, to make it obvious to whoever will be reading the tracker after you (especially if it's the person who can fix it). For example "problem with export" should be replaced with "artefacts when exporting NEF files with a small rotation enabled".
When closing a bug as Fixed, add a comment that includes the revision number of the first version without the bug. Linking to revisions is done with "commit:hash", where the hash should by the one of the commit containing the bugfix.
Always search for similar or duplicate requests before filing new reports.
When choosing which report should be marked a duplicate and which one left valid, older reports should be given priority over newer reports. Exceptions can be made if the newer report has significantly better information provided. Where appropriate, copy and paste across any relevant extra information as a comment to the bug report being left open.
Please do not randomly assign bugs or features to a developer or to the whole team ("Assignee: developers"). People will assign themselves if they want to work on a bug. If you know somebody that could contribute to a discussion or maybe knows a solution, add him/her to the watchers list rather than assigning the bug. He/she will be notified then.