09 Commitování a sémantické verzování

Vyvíjí-li se produkt, který se průběžně mění, je potřeba nějakým způsobem komunikovat jeho verze. Standardem na tomto poli je sémantické verzování.

Tím se rozumí označování verzí produktu trojčlenným číslem, které umožňuje komunikovat nejen to, že se verze mění, ale i jak.

major x.0.2:. To označuje hlavní verzi. Toto číslo se mění v případě, že se produkt změní některé ze svých API - tzn., že po upgrade nějaká dosavadní funkcionalita funguje jinak, nebo je vyřazena. Upgrade většinou vyžaduje dodatečnou kontrolu a úpravu napojeného kódu.

minor 1.x.2:. Toto číslo se mění v případě, když se do produktu přidají nové funkce, aniž by to ovšem narušilo dosavadní kód. Uživatelé tedy vědí, že si novou verzi mohou nainstalovat, aniž by se jim něco dosavadního rozbilo.

patch 1.0.x:. Toto číslo se mění zpravidla kvůli drobným opravám chyb. Uživatel tedy ví, že upgradovat by měl, ideálně co nejdříve.

Detailnější informace naleznete v dokumentaci SEMVER.

Určovat verzi zpětně a manuálně je složité a náchylné k chybám. Mnohem vhodnější způsob vydávání verzí je napárovat ho přímo na samotné změny. Při commitování, když známe charakter změny, můžeme do message vložit příznak (např. indikovat, že spravujeme chybu). Při release nové verze se pak provede analýza commitů a automaticky se odvodí správná verze.

Jak psát správně commit message i jak určit a vložit daný příznak je rozepsáno níže.

Ještě než se dostaneme k samotným doporučením psaním commitu, je nutné zmínit, že každá související skupina změn by měla mít svůj vlastní commit.

Změny obsažené v jednom commitu by měly být vždy logicky svázané. Ideálně by commit měl obsahovat každou změnu, která se týká operace popsané v commit message (např. úprava hlavičky) a nic dalšího. Další, nesouvisející změny kódu by měly být ve svých vlastních commitech.

Toto rozdělení dramaticky pomáhá chápat vývoj codebase nejen samotným vývojářům, ale umožňuje i snazší implementaci, přenášení změn, pozdější automatické zpracování, např. pro verzování, apod.

Při psaní commit zpráv na MUNI frameworku bychom měli dodržovat tyto konvence:

1. typ změny
2. Stručné a výstižné shrnutí dané změny
3. doplnění kontextu
4. jednotný jazyk a styl

Na začátku předmětu commit message (tzn. první řádek) uvedeme jednu z předdefinovaných možností, kterou indikujeme charakter změny. Na tomto příznaku závisí schopnost generovat verze a changelog.

Hlavní možnosti jsou tyto:

• feat
  Přidání či rozšíření funkce, nová komponenta nebo její stav atp.
  Budou-li v seznamu nových commitů při releasu některý s tímto příznakem, verze se zvýší o minor
  Změna bude zaznamenána v changelogu.
• fix
  Oprava chyby.
  Budou-li v seznamu nových commitů při releasu některé s tímto příznakem, verze se zvýší o patch
  Změna bude zaznamenána v changelogu.
• refactor
  Změny kódu, které nic neopravují ani nepřinášejí novou funkcionalitu.
  Verzi zvyšuje o patch
  Změna bude zaznamenána v changelogu.
• improvement
  rozšíření/zlepšení dosavadní funkcionality.
  Verzi zvyšuje o patch
  Změna bude zaznamenána v changelogu.
• perf
  Změny související především s optimalizací výkonu / nároků na výpočetní výkon.
  Verzi zvyšuje o patch
  Změna bude zaznamenána v changelogu.
• tpl
  Změny v šablonách.
  Verzi zvyšuje o patch
  Změna bude zaznamenána v changelogu.
• ui
  Změny vzhledu.
  Verzi zvyšuje o patch
  Změna bude zaznamenána v changelogu.
• style
  Změny kódu, jež neovlivňují jeho funkci (odsazení, doplnění středníků, formátování atp.).
  Verzi nemění
• content
  Úpravy ilustračních textů, obrázků. Těch věcí, které má jinak na starosti CMS.
  Verzi nemění
• docs
  Úprava dokumentace a ničeho dalšího.
  Verzi nemění
• test
  Přidání/úprava testů.
  Verzi nemění
• build
  Úpravy hlavně ohledně buildu projektu, např. gulp, npm atp.
  Verzi nemění
• config
  Úpravy konfigurací, např. eslint, gitignore, atp.
  Verzi nemění
• ci
  Úpravy hlavně ohledně správy projektu, např. nastavení CI atp.
  Verzi nemění
• chore
  Ostatní úpravy, které nemění zdrojové nebo testovací soubory
  Verzi nemění
• revert
  Používá se při revertu předchozího commitu.
  Verzi nemění
  Změna bude zaznamenána v changelogu.
• major verze je potřeba změnit ve chvíli, kdy se mění API. Tato změna může nastat při různých úpravých (např. velké refaktorování, redesign). Indikování je v tomto případě trochu odlišné od ostatních případů. Je nutné uvést BREAKING CHANGE na začátek těla commitu (tělo commitu je nový řádek, typicky oddělený prázdným řádkem od předmětu). Předmět se píše stejně jako běžně, commit message zvyšující verzi o major by tedy mohla vypadat takto:

  refactor: unify compoentA and componentB, change input data
  
  BREAKING CHANGE here can be another explanation and reasoning
  

Druhá nejpodstatnější věc je výstižný předmět. Ten už slouží ostatním lidem v týmu. Na cca 70 znacích bychom měli zaznačit, co daný commit provede. Př. Zvýraznění aktivní položky v postranním menu

Pokud je to vhodné, můžeme přidat tělo zprávy. Předmět odentrujeme, vložíme prázdný řádek a pak můžeme napsat klidně i pár odstavců, kterými vysvětlíme proč se změna provedla. Pokud v budoucnu někdo narazí na problém a bude potřebovat zjistit, proč je kód takový, může si v historii najít moment, kdy vznikl. Pokud v commitu je i tělo zprávy, může lehce pochopit, proč to tak je a jak přistoupit k další editaci.

Jelikož se předměty commitů později propíšou do changelogu (ty, které mění verze), je vhodné dodržovat jednotný styl zápisu. Především jazyk (zde čeština), malé/velké písmena, diakritika, atp.

Máme nastavený commitlint, který hlídá, zda je vyplněn typ změny. Nastavení je v souboru package.json. Používáme vlastní nastavení, které se hodí pro práci s šablonami. Dovoluje použití pouze těch klíčových slov, která jsou zapsána výše. Další možnosti nastavení jsou popsány v dokumentaci commitlintu.