Narazil som na krátky príspevok, ktorý obsahoval nasledovné:
~200 riadkov správy commitu pre zmenu +5/-8 @ #FreeBSD: https://freshbsd.org/freebsd/src/commit/9a2fac6ba65fbd14d37ccedbc2aec27a190128ea
To ma samozrejme prinútilo premýšľať. Je taký dlhý popis skutočne potrebný? A ak áno, je popis commit správy tým správnym miestom na jeho umiestnenie?
Je dlhý popis commit správy potrebný? #
Odpoveď na prvý popis commitu som si vedel racionalizovať pomerne ľahko. Áno. Áno, je nutné dokumentovať zmeny v čomkoľvek. Bez výhovoriek. Ak je popis zmeny taký zložitý, nech je. Pochvala každému, kto odvádza skvelú prácu.
Je popis commit správy tým správnym miestom? #
Táto otázka bola zložitejšia. Dôvod je, že existuje viacero miest, kde by sa podrobný popis mohol umiestniť. Okrem samotného popisu commit správy by zmeny mohli byť zdokumentované v komentároch kódu alebo v Pull Request (alebo Merge Request, či ekvivalente). Poďme to trochu rozanalyzovať.
Vkladanie popisu zmeny do komentárov kódu bolo praktikou pred tým, ako systémy na správu verzií s možnosťou pridania správy zmeny boli bežné. Tie časy sú dávno preč. Stále sa oplatí vkladať detaily do komentárov, ale nemali by sa navzájom odkazovať alebo na seba spoliehať. Pri tak dlhom popise, ako je tento, pokrývajúcom viacero riadkov, to pravdepodobne nie je dobrý nápad.
Na druhej strane, ukladanie detailov do Pull Request by tiež mohlo mať hodnotu, ale tam by sa dalo pomerne ľahko zmeniť a dôležité časti popisu by sa mohli stratiť, najmä preto, že platformy na hostovanie kódu ponúkajúce funkcionalitu Pull Request alebo Merge Request ju neponúkajú ako štandardizovanú funkciu, čo znamená, že dnes tam môže byť, ale zajtra zmiznúť.
Prepojenie medzi popismi #
Existuje ešte jeden aspekt toho všetkého. Je možné vložiť odkaz buď do popisu commit správy, do Pull Request alebo dokonca do komentárov. Ktorý z nich by mal byť kanonickým zdrojom?
Po premyslení je popis commit správy najlepším miestom, najmä ak je podporovaný platformou na hostovanie kódu, ktorá generuje trvalé odkazy na commity a ich popisy. Vytvorenie podrobného popisu commit správy a odkazovanie naň zo všade inde je spôsob, ako sa popis s dôležitými informáciami a zdôvodneniami ľahko nestratí, keďže zmena histórie commitov je veľmi odrádzaná prax.
Táto prax je podobná POSSE (Publish (on your) Own Site, Syndicate Elsewhere), hoci v kontexte tvorby obsahu. Ale kód a jeho správy sa tiež stávajú obsahom, takže pravdepodobne dáva zmysel začať s nimi tak zaobchádzať. Vložte kanonické poznámky k zmene commitu do popisu commit správy a odkazujte na ne (syndikujte) odtiaľ.
Toto je 69. príspevok #100daystooffload.