Project organization

The project is run by the maintainer, who balances developing and maintaining the software with the rest of a life. This calls for low-overhead project management strategies, relying on cloud-based collaborative tools.

Departments

Software development

Development is done on Github ,

Feature requests are not taken from users at this point. Users are consulted by the developer regarding their needs when a (re)design project is started. This is to prevent disruptive inputs at random times that would only slow-down the opened projects. Consultations reach beyond the forum and chat regulars — through surveys when the stakes warrant it — because the people who show up in project spaces are a biased sample of the people who use the tool, and silence is not satisfaction: those who left or never came have needs too, and they are precisely the ones the loudest channels never carry.

The time planning of issues being currently worked is available on the Kanban board . Developers can pick issues in the To Do column. New changes to watch and test are in the Done column. Pull requests that don’t follow the design protocol will be refused.

Developers who need help, an introduction to the code base, or code reviews can ask on the developer Matrix chat  or in GitHub Discussions ; mentorship is offered within the maintainer’s capacity.

Releases and stability

A stable release is a finished functional set, not a date: versions ship when what they promise works, and the triage rules define what lands in the next minor or major milestone. Two consequences. During foundation work — replacing a core library, reworking an architecture — feature work freezes until the foundations are done: building on a floor while someone replaces the joists wastes both people’s work. And there is no post-release rush: bugs found after a release enter the normal triage queue, in priority order, instead of triggering a scramble that itself creates regressions. Users who want to help stabilize a release test the candidate branch beforehand (validation), which is safe for your edits, unlike dev.

News about development projects closed or milestones are published on the blog. A dedicated Matrix chat  centralizes all updates and notifications from new commits, Github issues, new blog posts and new community forum posts.

Nightly builds

Installable packages for Windows (.exe) and Linux (.AppImage) are built automatically on Github around 1:00 am UTC, if new commits were pushed the day before. The direct download links are published to a dedicated Matrix chat , so you can get see the notifications pop and get the new builds, all in one place.

Nightly builds are meant to promote early testing from users who can’t or don’t want to build themselves from source. They can be instable.

Bugs

Bugs (as in, stuff that breaks the software), are handled on Github  when they are confirmed.

They can be discussed in GitHub Discussions  or the Matrix chats , especially to confirm that they are actually bugs (and not design changes).

Opening issues on Github is important to include them to the project management and track them from a single place.

Website

The website is generated using Hugo static website builder , which is a fairly low-overhead way of writing technical websites using Markdown syntax.

The source code of the website is on Github . You can correct typos or help translating directly by editing the source files on Github UI. Otherwise, you can install Hugo on your computer, then the Readme file on Github explains how to build a preview website locally, using a test server on your computer, to better preview (and debug) your changes.

Changes to the website have to use the typical Git + Pull Request (on Github) workflow, which can deter non-programmers, but it’s the least shitty way of remote-collaborating on somethng text-based, while ensuring reversible versionning and backups.

Documentation

The documentation is not included in the website repository for licensing reasons (GPL v3), so it is imported as an external Hugo module. The source code is on Github , and everything else applies the same as for the website. The Readme presents the available shortcodes that you can use to format the content, in Markdown files.

There is a caveat, though, if you want to build the documentation locally, because it imports the theme from the main Ansel website, so the easiest way is actually to build the main website while linking locally the documentation as a module. The procedure is detailed on the Readme of the main website.

The documentation is currently undergoing structural changes, along with software design changes, so don’t hesitate to ask on Matrix  if you have a particular project in mind, before you commit to something on the verge of being removed.

Teaching and user education

As many “bugs” report show, insufficiently-trained users have wrong expectations, and if you take their feature requests too seriously, you end up with crippled software duplicating features and CPU load. Those need to be solved at the root : with teaching.

1. Video tutorials are published and indexed from the workflows section,
2. Educational long-form writing belongs on the website or in GitHub Discussions ,
3. The documentation is meant to provide usage information closely tied to the software GUI, so users could learn about the features in linear order of GUI appearance.
4. The main website workflow section is meant to provide usage information tied to a specific task to achieve, so users could learn “how to”.
5. The main website resources section is meant to provide background theoritical information to help building a deeper understanding of color and photography, and empower users to troubleshoot retouching issues themselves.

Management

This is mostly a one-guy operation, so things have to be efficient and low-overhead. Which requires some discipline.

Programming management

There are usually 2 open programming projects at the same time, that are chosen because independent from each other. This allows to switch to project #2 while waiting for user feedback on changes made in #1, in a way that still allows to identify which one created regressions and new bugs. Think of it as alternate single focus.

In the middle of a project, the developer will typically not deal with, care about nor listen to issues related to anything but that project, because brainpower is a precious resource, faster spent than recovered. In particular, feature requests on other parts of the software will be disregarded.

The day-to-day focus is subjected to change unexpectedly, depending on the shit uncovered while fixing other shit, thanks to Darktable crappy legacy of semi-broken non-modular madness-inducing spaghetti code, which often requires partial or full rewrites (in any case, cleaning up) before attempting to fix anything (in a way that doesn’t induce more future problems, that is).

Communication

We live in a World where the volume of information and communication has become overwhelming and humans don’t have the bandwidth to process all of it. Endless threads and unregulated conversations are actively harming communication by diluting important information and exhausting the reader. Discussion is solely meant to reach an understanding and proceed to actionable decisions. There is a subtle trade-off between completeness and conciseness to find.

For chat or general questions, please use the Matrix space . But even there, conciseness is key.

In pull requests and issues, on Github please try to stay concise and on-point :

• Technical details (like OS, use of OpenCL, screen size, etc.) should make use of bullet-point lists.
• Screenshots and drawings can go a long way.
• If you are replying to a particular point or person, quote the section of text you are replying to.
• Break your text into paragraphs of roughly 4 to 8 lines, but avoid sending each sentence to a new paragraph.
• Keep in mind everybody speaks English but very few people are native speakers, so try to stick to basic Globish .

Good principles on issues/tickets interactions can be found here .

Updates and notifications

Many centralized and automated ways are offered to keep track of what’s new in the project :

• The main website has a central RSS feed, where new and updated page goes : global RSS,
• For more granularity, each section of the website (News, Doc, Workflows, etc.) has its own RSS feed too. The icon you find on section index pages and on every page links to that RSS feed in the current language.
• Code changes can be tracked from commits index on Github , or using the Github Atom feed  (truncated to the 20 most recent commits). Commit messages are usually quite verbose and should explain well enough what was changed and why.
• New commits, Github issues updates (created, edited, closed), new community posts and new website pages are all posted to a dedicated Matrix chat .
• Nightly builds packages are posted to a dedicated Matrix chat . They are also listed on the Github pre-release page .
• Open and closed project/issues can be seen on the Github Kanban board .