/ Tipy a Triky

3 triky pre lepšie git repo

Coding style je dosť závislý od programovacieho jazyka, avšak sú aj triky ohľadom gitu, ktoré sa oplatí dodržiavať a ktoré by mal vedieť každý programátor. V tomto krátkom článku vás s nimi zoznámim.

1. Changelog (zoznam zmien)

Áno, aj napriek tomu, že existujú git commit správy je vhodné ho udržiavať. Bežná konvencia je že sa nachádza v koreni projektu. Inak povedané ak máte projekt v zložke "/home/spodlesny/Documents/mojprojekt" tak changelog bude umiestnený v "/home/spodlesny/Documents/mojprojekt/changelog.md".

Prípona md značí že sa jedná o Markdown. Mimochodom v tom istom jazyku píšem tento blog :)

Pravidlá

Pravidlá ako písať changelog sú závislé od konvencie, ktorú použijete. Po pravde ani veľmi na výber z konvencii nie je. Existuje niečo ako GNU NEWS file "príručka", ktorá má až dva paragrafy.

Osobne sa pridržiavam pravidiel z https://keepachangelog.com/sk/1.0.0/ ktoré sú dostatočne jednoduché, pričom výsledný changelog je čitateľný aj pre netechnických uživateľov.

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2017-06-20
### Added
- New visual identity by @tylerfortune8.
- Version navigation.
- Russian translation from @aishek.
- Czech translation from @h4vry.
- Slovak translation from @jkostolansky.

### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed
- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03
### Added
- RU translation from @aishek.
- pt-BR translation from @tallesl.
- es-ES translation from @ZeliosAriex.


Ako môžete vidieť, ukážka je dostatočne pochopiteľná aj bez vysvetlenia. Typy zmien (Added, Removed, Changed, ...) a hlavné pricípy z ktorých Changelog vychádza si môžete v Slovenčine prečítať na: https://keepachangelog.com/sk/1.0.0/#how

Ešte by som na záver tejto kategórie upozornil že odporúčane je používať formát dátumu ISO 8601 to jest ten hovadský formát typu Rok-Mesiac-Deň (2018-04-20). Aj keď si myslím že je to ten najhorší formát na čas, v IT je to štandard, tak sa ho držte.

2. Verzovanie

Changelog popísaný vyšie používa na verzovanie formát typu A.B.C, kde:

  • A reprezentuje novú verziu, ktorá je nekompatibilná (napr. na úrovni API) s predchádzajúcou verziou
  • B reprezentuje novú verziu s menšími úpravami a spätnou kompatibilitou
  • C reperezentuje väčšinou patche a opravy chýb

Priklad

Máte program, ktorý sa spúšta: ./hello.py --name "Čitateľ"

Je to prvá funkčná verzia tak ju pomenujeme 1.0.0

Zistíme že nám to vypíše AhojČitateľ namiesto Ahoj Čitateľ. Zároveň to spadne keď je na vstupe české "ř". Tak to opravíme, a vydáme to ako verziu 1.0.1

Super, všetko funguje tak ako má, avšak zákazníkovy sa to nepáči, lebo nevie po anglicky a nevie čo "name" znamená. Zmeníme teda príkaz na ./hello.py --meno "Čitateľ" a ./hello.py --name "Čitateľ" znefunkčníme. Je to nová verzia, ktorá nie je kompatibilná so starou tak ju pomenujueme ako 2.0.0

Potom nám povie že by si chcel určiť aj pozdrav a teda aby sa to spúštalo ako ./hello.py --meno "Čitateľ" --pozdrav "Ahoj". Spravíme potrebné zmeny a označíme to ako verziu 2.1.0

Changelog by vyzeral nasledovne:

# Changelog

## [Unreleased]
- implementovať blockchain

## [2.0.0] - 2017-06-21
### Added
- nový switch pre definovanie pozdravu

## [2.0.0] - 2017-06-21
### Changed
- switch --name premenovaný na --meno

## [1.0.1] - 2017-06-21
### Fixed
- pridaná chýbajúca medzera pri pozdrave na stdout

## [1.0.0] - 2017-06-20
### Added
- vypíše Ahoj [meno]

3. Git commit správy

Platí všeobecné pravidlo že čo commit, to zmena. Znamená to, že by ste nemali mať jeden commit, ktorý opravuje dva bugy, pridáva tri featury a k tomu pridáva jednu lokalizáciu.

Zase platí že čo programátor, to iná sémantika. Do nedávna som sa ani ja neriadil žiadnou špecialnou, potom mi kamarát zaslal nasledujúci link a uvedomil som si ako by mi to uľahčilo život, keby som sa toho držal. Ľahšie by sa mi totiž filtrovali commit správy pre prehľadávaní starších projektov.

Formát

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Zhrnutie v prítomnom čase.
|
+-------> Typ: chore, docs, feat, fix, refactor, style, or test.

Zdroj: https://seesparkbox.com/foundry/semantic_commit_messages

  • chore
    • všetko čo sa nehodí do ostatných typov :)
    • väčšinou malé, nepodstatné zmeny, úpravy, tasky
  • docs
    • dokumentácia/popis funkcii, tried a častí kódu
  • feat
    • featury (vylepšenia, nová funkcionalita)
  • fix
    • oprava chýb v kóde
    • trik: ak používate Bitbucket a integrovaný issue tracker, commit správa typu: fix: fixing issue #1 automaticky označí issue číslo 1 ako resolved (vyriešené) v issue trackery. Ďalšie podobné triky a keywordy (kľúčové slová) môžete nájsť v dokumentácii Bitbucketu.
  • refactor
    • refactoring (uprava) kodu
  • style
    • uprava vystupov
  • test
    • testovacie skripty, obmedzujuce podmienky a pod

Bonus: Ako správne na vetvenie

Branche alebo po Slovensky vetvy sú pre začiatočníkou asi to najťažšie na celom gite. Hlavne pull requesty, merge a nočná mora merge konflikty. Celá problematika git-u a branch-ov je na vlastný článok. Tak teda aspoň v skrakte. Ako správne pomenovať a kedy vytvoriť branche?

Kedy vytvoriť novú vetvu?

Jedna zo zásad je vytvoriť novú vetvu vždy, keď pracujete na novej zmene. To je super, ale čo je nová zmena? Vytvorim si novú vetvu, lebo robím na novej feature. Pushnem tam kód, potom objavím bug a mám vytovoriť novú vetvu aby som ho fixol?

Nie tak úplne. Osobne sa držím týchto zásad:

  • master vetva udržuje funkčný kód
  • robím featuru alebo zmeny v kóde, vytvorím si novú vetvu
  • pokiaľ na novej vetve robím sám tak robím zásahy do kódu priamo, inak si vytvorim novú vetvu v ktorej pracujem a ktorú potom mergenem s rodičovskou (s ktorej vychádza)
  • keď je všetko čo som chcel spraviť hotové, je čas mergnuť moju vetvu do master vetvy. Ak pracujem na projekte sám, mergnem to priamo, inak vytvorím pull request a počkám kým to niekto review-ne a mergne za mňa.
  • pokiaľ pracujem na projekte úplne sám, pushujem zmeny priamo do mastera a nevytváram zbytočné vetvy. Jediná vedľajšia vetva ktorú udržujem je deployment

Príklad

Screenshot-from-2018-04-21-08-28-08-1
Zelená je master, ružová (alebo skôr svetlo-fialová?) je vetva v ktorej sa vyvýja a čierna vetva je pre fix (v tomto pripade refactoring a novu featuru). V druhom commite od vrchu je možné vidieť merge dvoch vetví a taktiež číslo pull requestu.

Dobré je taktiež udržiavať tzv. deployment vetvu, ktorá zrovna beží na produkcii a ktorá sa vždy mergeuje s master vetvou. Uľahčí vám to prácu pri aktualizácii produkcie na novšiu verziu a zníží riziko že odpálite produkciu kvôli pozmenenej konfiguácii.

Ako pomenovať nové vetvy?

To je úplne na vás. Väčšinou je dobré krátke slovo, alebo slovné spojenie ktoré to vystihuje. Ako je aj na ukážke. Parser vetva rieši parsovanie textu (v tomto aktuálnom prípade zdrojového kódu) a vetva str-refcounter rieši počítanie referencii na dané stringy (funkcie, premenne a pod). Pre bugy a featury s ticketom v issue trackery môžete taktiež použiť konvenciu bug-ID, kde za ID dosadíte ID bugu/featury v issue trackery.


Tot vsjo na dnes. Nakoľko som nedávno rozbehal komentáre, môžete sa vyjadriť, prípadne napísať otázky alebo kritiku priamo pod článok :)