Issues

Issues nejsou vlastností čistého Gitu, ale GitLabu jako takového. Setkáte se s nimi ale i v ostatních verzovacích systémech jako například GitHub.

Používá se jako takový "úkolníček". Jedno issue by mělo reprezentovat jeden problém, návrh nebo zkrátka cokoliv, co je v projektu potřeba udělat.

Jak vytvořit issue

Issue se vytváří vždy ve webovém rozhraní GitLabu. Otevřete v GitLabu projekt, ke kterému chcete vytvořit issue. V levém panelu otevřete Plan -> Issues.

Nyní vidíte seznam issues pro tento projekt. Issue vytvoříte kliknutím na New item. Ukáže se formulář pro vytvoření issue.

Co napsat do title?

Nadpis by měl krátce vystihovat, o co v issue jde. Nepatří sem žádné podrobné popisy toho, co je špatně, nebo konkrétní návrhy řešení. Nadpis má být stručný a jednoduchý.

Jak mají vypadat issue titles:

• Kalibrace nefunguje pro záporné hodnoty
• Přidat podporu pro GPIO
• Zadokumentovat nové funkce
• Vypadává komunikace po SPI

Jak nemají vypadat issue title:

• Nefungující věci
• Chtělo by to používat pro ovládání GPIO - ideálně pomocí pygpiod knihovny
• Asi by to možná někdy chtělo dokumentaci
• Občas vypadává komunikace po SPI - ale pouze když jsou posílána data s negativními hodnotami nebo když je kočka na střeše

Co napsat do description?

Popis issue by měl obsahovat všechny informace, které by mohly pomoci s vyřešením issue. Popis by měl obsahovat i odkazy na obrázky, videa, dokumenty atd. V případě chyby klidně log z aplikace, postup pro reprodukci chyby apod. Pokud se jedná o nějaký návrh, neuškodí přidat obrázek s návrhem nebo podrobnější popis.

Obecně by popis měl obsahovat následující informace

Bug

• Přesný postup k reprodukci chyby
• Popis toho, co přesně se chová špatně
• Popis, jak se to má chovat správně
• Ideálně log aplikace, když chyba nastane (u HW např. obrázek shořelé desky :D)

Featura

• Popis toho, jak se to chová teď
• Popis toho, co je na aktuálním chování nedostačující
• Jak by bylo lepší, aby se to chovalo

Jak funguje označování

Při jakémkoliv psaní na GitLabu (issue, MR, review nebo klasický komentář) můžete označovat určité prvky. Označování provedete tak, že napíšete identifikační znak a následně číslo konkrétního prvku. Každý prvek má svůj identifikační znak. Jakmile napíšete identifikační znak, otevře se Vám nabídka, ze které stačí vybrat prvek, který chcete označit.

Seznam identifikačních znaků

• @ - Pro označení uživatele
• # - Pro označení Issue
• ! - Pro označení Merge requestu

Funguje i URL

Pokud se prvek, který chcete označit, nachází v jiném repozitáři, je to trochu obtížnější. V tomto případě je nejjednodušší zkratka vložit url. GitLab jej po odeslání interpretuje jako prvek, na který ukazuje.

Nastavení přiřazení

Každé issue má tzv. 'assignee'. To značí uživatele, který bude pracovat na tomto issue. Každá firma má odlišnou ideologii, jak s assignee pracovat.

Standardně se ale při vytváření issue žádný assignee nevyplňuje. Vývojář, který má danou část projektu na starosti (nebo správce projektu), si issue přiřadí sám v momentě, kdy na něm skutečně začne pracovat. Díky tomu je možné si udržet přehled o tom, kdo na čem aktuálně pracuje.

Označujte vývojáře

I když by se assignee jako takový při vytváření uživatele vytvářet neměl, tak člověk, který má projekt na starosti musí být k issue nějak přiřazen. Placený GitLab na to má své features, ale my, kteří máme pouze komunitní verzi GitLabu, si musíme poradit poněkud kreativněji.

Stačí člověka, po kterém chceme, aby na issue pracoval, označit v popisu issue.

Jak se issue uzavírá

Issue se uzavírá, jakmile je vyřešené. To se může stát, pokud je problém doopravdy opraven, nebo pokud se ukázalo, že je issue neplatné (problém ve skutečnosti neexistuje).

V každém případě se issue neuzavírá bez poznámky. Vždy je důležité při zavírání issue vytvořit krátkou zprávu o tom, co se stalo. Tzn. proč se zavírá - kde se problém projevil a kde ne a na základě čeho se tedy zavírá. Ideálně i s referencemi do patřičných míst.

Logování času

Pokud budete v issue vyplňovat čas, který jste stravili nad řešením, přinese to spoustu výhod pro sledování stavu projektu. Více se dozvíte v kapitole Sledování času

Způsoby uzavření issue

Ručně z webového rozhraní

Issue lze zavřít velmi jednoduše pomocí tlačítka "Close issue" ve webovém rozhraní GitLabu. Při zavření issue tímto způsobem nezapomeňte dodat příslušný komentář.

Automaticky z commitu

Jedná se o mírně pokročilou metodu pro zavírání issue. Pokud commitnete a do commit message napíšete jedno z klíčových slov a následně odkaz na issue, issue tím dokážete uzavřít. Tímto způsobem lze na issue i pouze referovat v rámci commitu bez uzavření. Povolená klíčová slova pro uzavření issue jsou: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. Tento způsob se používá při malých issues, které se opravují v rámci jednoho commitu. U větších issues je vhodnější je zavřít pomocí MR.

Příklady

• 'Fix regulator parameters (close #123)' - uzavře issue s ID 123
• 'Add more log (close #6)' - uzavře issue s ID 6
• 'Add input parameter check (#44)' - referuje na issue s ID 44
• 'Add output parameter check (closes #44)' - uzavře issue s ID 44

Proč používat reference

Reference na issue je vhodné používat pro zpětné trackování změn. Jedná se o velmi silný nástroj, když se snažíte zjistit, co a proč se změnilo od doby, kdy vám to "ještě fungovalo". Pokud třeba vypozorujete, že přidáním této featury vám nějaká část aplikace přestala fungovat, tak právě díky těmto referencím lze zpětně dohledat, kde všude v kódu nastala změna, a chybu tak snáze odhalit.

Automaticky z merge requestu

Funguje stejně jako automatické uzavření z commitu. Toto specifické značení se ale nezadává do commit message, ale do popisu merge requestu. Pokud je totiž MR správně nastavený (viz výše), připojené issue se uzavírá automaticky. Více o tom najdete v kapitole Merge request.

Jak se rozhodnout, který způsob použít

• Jakmile vyřešení issue nevyžadovalo změnu ve zdroji, zavřete jej pomocí webového rozhraní
• Pokud bylo issue pouze v rámci jedné pracovní větve a bylo vyřešeno jedním commitem, zavřete jej pomocí reference v commitu
• Pro větší issue vytvořte MR a v případě potřeby (ideálně) nechte zkontrolovat dalším vývojářem