Triaging issues

This page is written for people helping triaging issues on the issue Github tracker.

Preamble

• Any project has limited resources, the difference between projects will be the threshold.
• Any project should have clear goals. For Ansel, it is to manage, edit and export collections of RAW images on a desktop computer by an end-user who is not a CLI user but puts visual image quality above all else.
• Any project has overhead, that is actions requested to meet the goals, although they are not directly the goal and therefore should stay minimal. For Ansel, it is the maintenance of the website, documentation, servers, nightly-built packages, code cleanups, debugging, regression tests, cross-OS support, issues triaging, etc.
• Goals and overhead should be expressed in terms of tasks to perform in order to solve problems (issues),
• because of resource limitation, tasks have to be ordered depending on their priority.

The following document aims at defining this priority.

Ansel was forked on Darktable because Darktable has no clear goal, no priority management, and the overhead is increasing every year.

Defining good issues

Project management works better with SMART tasks. SMART stands for:

• Specific (ex: finding URI of pictures Ansel exported on the filesystem and open them)
• Measurable (ex: number of clicks/steps required, CPU time to perform the task on some target platform)
• Actionnable/Achievable (ex: can be integrated on current code base with only minor rewrites, needs only a few hundreds of lines of code)
• Relevant/Reasonable (ex: is part of a fairly-general photography workflow, would be used by a signicative part of users)
• Time-bound (ex: requires at most 70 man-hours).

A good issue is one that leads to a SMART task. For Ansel, that means issues focusing on a clearly-defined problem affecting a clearly-defined step of the picture editing workflow ("I have problems doing X because Y and I would like Z").

Questions and general discussions should happen on https://community.ansel.photos.

Bad issues are:

• too broad ("automatize workflow", "improve UX"),
• focusing on the means ("use neural network", "extend tone curve") instead of the goal ("mask the sky out", "control saturation selectively"),
• out of scope ("port to Android", "switch to Qt", "switch to Vulkan")
• affecting third-party libraries/projects (Rawspeed, Libraw, Exiv2, Lensfun, GPhoto2, Gtk, etc.),
• too subjective ("please do things like that other software I used in the past and really like").

Side note: some issues may sound like things in need for more code, whereas they actually need better documentation of current features, or slight GUI touch-ups (renaming labels, reorganizing widgets), so that's something to keep in mind before jumping on the guns.

Defining priorities

In an ideal world, tasks (aka good issues) would be added to the to-do list in a linear fashion, as milestones are reached, and their code product would be tested for a couple of weeks while the code is otherwise frozen, until it is proven that everything holds, in which case we would unfreeze the code and move on to the next task in the to-do list.

Problem is this implies everybody on deck for the testing phase, so it doesn't freeze the code for too long. Because that doesn't happen (people take vacations, have kids, move homes, change jobs, have a life…), we have to parallelize testing the product of previous tasks while we are working on the next, to be efficient.

This is to say the to-do list is not linear and some important things might get added or removed dynamically, depending on what happens. The problem is then to determine what constitutes something important enough as to disrupt the schedule.

There is no definitive rule here, so you will have to use your best judgment, but there are some rules of thumbs:

• something recently broken (a regression) is easier to spot and fix sooner than later, so in the grand scheme of things, it might be less work overall to do it sooner,
• something that prevents the software from working at all (crash, corrupted output files, loss of data) is critical enough to take precedence over improvements and more cosmetic fixes,
• something that impacts a large number of users and where no work-around can be found will take precedence too.

On the contrary, anything impacting a small number of users, or niche/secondary features, or minor annoyances that have work-arounds, are not critical enough to justify disrupting the schedule. Those will be added on top of the queue.

Defining milestones

Modules parameters are saved as binary blobs. We deal with these by handling their bit size. When a new parameter is added, we need to write code to handle the conversion, aka the different bit size of the parameter blob, and we increase the internal version of modules parameters. No code is written for backward compatibility, so pictures edited with newer modules can't be opened in older modules. Modules parameters are used in styles, in presets and in XMP files too.

For these reasons, any issue that would lead to adding parameters in modules (either the image processing modules in darkroom, or the lighttable modules dealing with export & metadata), needs to be planned for the next major version of the software (1.0, 2.0, 3.0, etc.). This means that only GUI & behaviour changes are allowed within the same major version, and can be planned for the next minor version (0.1, 0.2, 0.3, etc.).