Issues triëren

Deze pagina is geschreven voor mensen die helpen bij het triëren van issues in de issue-tracker op Github.

Preamble

• Elk project heeft beperkte middelen, het verschil tussen projecten zit in de drempelwaarde.
• Elk project zou duidelijke doelen moeten hebben. Voor Ansel is dat het beheren, bewerken en exporteren van collecties RAW-beelden op een desktopcomputer door een eindgebruiker die geen CLI-gebruiker is maar visuele beeldkwaliteit boven alles stelt.
• Elk project heeft overhead, dat wil zeggen handelingen die nodig zijn om de doelen te halen, hoewel ze niet direct het doel zijn en daarom minimaal zouden moeten blijven. Voor Ansel is dat het onderhoud van de website, documentatie, servers, nachtelijk gebouwde pakketten, code-opschoningen, debuggen, regressietests, cross-OS-ondersteuning, het triëren van issues, enz.
• Doelen en overhead zouden uitgedrukt moeten worden in termen van taken die uitgevoerd worden om problemen op te lossen (issues). Als er geen probleem is om op te lossen, dan is er geen werk te doen: de status quo is ook prima, creëer geen werk om het werk zelf.
• vanwege de beperking van middelen moeten taken geordend worden op basis van hun prioriteit.

Het volgende document heeft als doel deze prioriteit te definiëren.

Ansel is afgesplitst van Darktable omdat Darktable geen duidelijk doel heeft, geen prioriteitenbeheer, en de overhead elk jaar toeneemt, wat het handelsmerk is van burn-outfabrieken en op middellange termijn onhoudbaar is.

Goede issues definiëren

Projectbeheer werkt beter met SMART-taken. S.M.A.R.T. staat voor:

• Specifiek (bv.: de URI vinden van foto’s die Ansel op het bestandssysteem heeft geëxporteerd en ze openen)
• Meetbaar (bv.: aantal klikken/stappen dat vereist is, CPU-tijd om de taak op een bepaald doelplatform uit te voeren)
• Actiegericht/Haalbaar (bv.: kan met slechts kleine herschrijvingen in de huidige codebasis geïntegreerd worden, heeft slechts een paar honderd regels code nodig)
• Relevant/Redelijk (bv.: maakt deel uit van een tamelijk algemene fotografieworkflow, zou door een significant deel van de gebruikers gebruikt worden)
• Tijdgebonden (bv.: vereist hooguit 70 manuren).

Een goede issue is er een die tot een SMART-taak leidt. Voor Ansel betekent dat issues die zich richten op een duidelijk gedefinieerd probleem dat een duidelijk gedefinieerde stap van de fotobewerkingsworkflow beïnvloedt (“Ik heb problemen met het doen van X vanwege Y en ik zou graag Z willen”).

Vragen en algemene discussies horen plaats te vinden op https://community.ansel.photos.

Slechte issues zijn:

• te breed (“workflow automatiseren”, “UX verbeteren”),
• gericht op de middelen (“neuraal netwerk gebruiken”, “tooncurve uitbreiden”) in plaats van op het doel (“de lucht wegmaskeren”, “verzadiging selectief regelen”),
• buiten de scope (“naar Android overzetten”, “overstappen naar Qt”, “overstappen naar Vulkan”)
• die bibliotheken/projecten van derden beïnvloeden (Rawspeed, Libraw, Exiv2, Lensfun, GPhoto2, Gtk, enz.),
• te subjectief (“doe alsjeblieft dingen zoals die andere software die ik in het verleden gebruikte en echt leuk vind”). Wat gebruiker A leuk vindt, zal door gebruiker B afgekeurd worden, daar kunnen we niet mee werken.

Kanttekening: sommige issues klinken misschien als dingen die meer code nodig hebben, terwijl ze in werkelijkheid betere documentatie van bestaande functies nodig hebben, of kleine GUI-aanpassingen (labels hernoemen, widgets herorganiseren), dus dat is iets om in gedachten te houden voordat je in het diepe springt.

Prioriteiten definiëren

In een ideale wereld zouden taken (oftewel goede issues) op een lineaire manier aan de takenlijst worden toegevoegd, naarmate mijlpalen bereikt worden, en zou hun codeproduct een paar weken getest worden terwijl de code verder bevroren is, totdat bewezen is dat alles standhoudt, in welk geval we de code zouden ontdooien en verdergaan met de volgende taak op de takenlijst.

Het probleem is dat dit iedereen aan dek vereist voor de testfase, zodat de code niet te lang bevroren blijft. Omdat dat niet gebeurt (mensen gaan op vakantie, krijgen kinderen, verhuizen, wisselen van baan, hebben een leven…), moeten we het testen van het product van vorige taken parallel uitvoeren terwijl we aan de volgende werken, om efficiënt te zijn.

Dit betekent dat de takenlijst niet lineair is en dat sommige belangrijke dingen dynamisch toegevoegd of verwijderd kunnen worden, afhankelijk van wat er gebeurt. Het probleem is dan om te bepalen wat iets belangrijk genoeg maakt om de planning te verstoren.

Er is hier geen definitieve regel, dus je zult je gezond verstand moeten gebruiken, maar er zijn een paar vuistregels:

• iets dat recent kapot is gegaan (een regressie) is makkelijker vroeg dan laat op te sporen en te herstellen, dus in het grote geheel kan het al met al minder werk zijn om het eerder te doen,
• iets dat de software helemaal belet te werken (crash, beschadigde uitvoerbestanden, gegevensverlies) is kritiek genoeg om voorrang te krijgen boven verbeteringen en meer cosmetische reparaties,
• iets dat een groot aantal gebruikers treft en waarvoor geen tijdelijke oplossing gevonden kan worden, krijgt eveneens voorrang.

Daarentegen is alles wat een klein aantal gebruikers treft, of nichefuncties/secundaire functies, of kleine ergernissen waarvoor tijdelijke oplossingen bestaan, niet kritiek genoeg om het verstoren van de planning te rechtvaardigen. Die worden op een first-in/first-out-manier aan de wachtrij toegevoegd.

Ansel heeft 4 prioriteitsniveaus, ingesteld als issue-tags:

• priority: critical: Treft basis- en kernfunctionaliteiten van de software op een manier die belet dat ze überhaupt werkt,
• priority: high: Treft basis- en kernfunctionaliteiten van de software op een manier die de bruikbaarheid ernstig verslechtert,
• priority: medium: Treft basis- en kernfunctionaliteiten van de software op een manier die de bruikbaarheid licht verslechtert (tijdelijke oplossingen beschikbaar),
• priority: low: Treft optionele en nichefunctionaliteiten

Mijlpalen definiëren

Moduleparameters worden opgeslagen als binaire blobs. We gaan hiermee om door hun bitgrootte te beheren. Wanneer een nieuwe parameter wordt toegevoegd, moeten we code schrijven om de conversie af te handelen, oftewel de andere bitgrootte van de parameterblob, en we verhogen de interne versie van de moduleparameters. Er wordt geen code geschreven voor achterwaartse compatibiliteit, dus foto’s die met nieuwere modules bewerkt zijn kunnen niet in oudere modules geopend worden. Moduleparameters worden ook gebruikt in stijlen, in presets en in XMP-bestanden.

Om deze redenen zou elke issue die zou leiden tot het toevoegen van parameters in modules (hetzij de beeldverwerkingsmodules in de donkere kamer, hetzij de lichttafelmodules die met export en metadata omgaan) de achterwaartse compatibiliteit breken en moet die gepland worden voor de volgende hoofdversie van de software (1.0, 2.0, 3.0, enz.). Dit betekent dat binnen dezelfde hoofdversie alleen GUI- en gedragsveranderingen zijn toegestaan, en dat die gepland kunnen worden voor de volgende subversie (0.1, 0.2, 0.3, daarna 1.1, 1.2, 1.3, enz.).

Ansel heeft te allen tijde slechts 2 mijlpalen: de volgende subversie en de volgende hoofdversie.

Moeilijkheid definiëren

Moeilijkheid houdt direct verband met de hoeveelheid werk die een taak vereist, dat wil zeggen:

• het aantal regels code dat geschreven moet worden,
• het aantal bestanden dat gewijzigd moet worden,
• de kans op het breken van bestaande functies, wat tot extra testwerk leidt,
• het bestaan van vergelijkbare functies of geschreven theorie om de taak te volbrengen,
• de overhead van het betrouwbaar laten werken van wijzigingen en functies op verschillende besturingssystemen.

Moeilijkheid op een accurate manier inschatten is iets wat alleen een ervaren ontwikkelaar kan.

Aard definiëren

De aard van de issues wordt afgehandeld met labels. We hebben:

• regressies (dingen die werkten maar die door tamelijk recente wijzigingen kapot zijn gegaan),
• bugs (dingen die de afgelopen jaren nooit gewerkt hebben),
• verbeteringen (dingen die verbeterd of toegevoegd moeten worden),
• wontfix (geen bug, maar een functie of ontwerpkeuze of noodzaak opgelegd door afhankelijkheden van derden),
• question (hoort niet op Github, maar op https://community.ansel.photos),
• duplicate (issue al gemeld),
• unclear (issue kan niet begrepen worden),
• invalid (issue is “slecht” volgens de bovenstaande definitie van een goede issue).

Prioriteiten zijn relatief

Zie https://www.youtube.com/watch?v=8fnfeuoh4s8 . De auto moeten repareren om het lampje te vervangen is een prachtige metafoor voor het werken aan code van 12 jaar oude software met honderdduizenden regels code, geschreven door mensen die niet met elkaar praatten en hun wijzigingen niet documenteerden. De auto repareren is geen topprioriteit totdat het de voorwaarde wordt om het lampje met hoge prioriteit te repareren.

Jouw triage-taak

Uiteindelijk zal alleen een ervaren ontwikkelaar issues accuraat kunnen triëren. Maar de rede vereist dat een ervaren ontwikkelaar ingezet zou worden om dingen te doen die alleen een ervaren ontwikkelaar kan doen: eenvoudige code schrijven om technische problemen die enige theorie en ontwerp vereisen efficiënt op te lossen.

De afweging is om triagers te laten helpen bij het prioriteren van voor de hand liggende issues, zodat ontwikkelaars alleen met de minst voor de hand liggende issues te maken hebben en zich op het coderen kunnen concentreren.

1. label alleen issues die je begrijpt en waarbij je je op je gemak voelt om te triëren. Je hoeft ze niet allemaal te doen, het is prima als je het niet weet.
2. voor issues die je begrijpt:
   • ken een prioriteitslabel toe als je kunt,
   • ken een aard-label toe als je kunt,
   • ken een mijlpaal toe als je kunt,
   • sluit de issue onmiddellijk als die invalid of duplicate is.
3. voor issues die je niet begrijpt:
   • probeer de auteur meer vragen te stellen,
   • zorg dat auteurs alle relevante info invullen (OS, hardware, reproductiestappen voor bugs),
4. het is beter dat je niets doet dan dat je het verkeerd doet: issues zonder labels zijn makkelijker op te sporen dan issues met verkeerde labels.
5. aarzel niet om videovergaderingen bijeen te roepen: beter 30 min samen zitten voor een productief gesprek en beslissingen bijstellen dan eindeloze threads van nutteloze berichten uitwisselen.

Bedankt !