Problem

W naszej firmie zauważyliśmy, że dobrze napisane wiadomości commitów mogą znacznie poprawić jakość procesu code review i ułatwić rozwiązywanie konfliktów w kodzie poprzez git, ale sama świadomość problemu nie wystarczy by poprawić sytuację. Narzekanie za każdym razem z arbitralną listą skarg na jakość wiadomości w commitach jest nieproduktywne i wyczerpujące dla obu stron konwersacji. Potrzebowaliśmy standardu, idealnie, standardu, który można zweryfikować automatycznie. Spośród wielu trendów w commitach git, jeden z nich przyciągnął naszą uwagę - specyfikacja conventional commits. Postanowiliśmy zacząć jej używać i wymusić jej przestrzeganie za pomocą najesz infrastruktury do Continous Integration.

Czym są conventional commits i jak mogą pomóc?

Conventional commits standaryzują strukturę commitów, wprowadzając pojęcie typu, zakresu i innych elementów w wiadomości. Typ rozpoczyna wiadomość i sygnalizuje rodzaj zmiany, którą commit wprowadza. Samo dodanie struktury do commitów nie wystarczy, aby zapewnić lepszą jakość komunikacji, ale zmuszenie deweloperów do zatrzymania się na chwilę, aby wybrać odpowiedni typ commitu przed jego wysłaniem, już okazało się dość korzystne. Istnieją także inne korzyści, których nie rozważaliśmy, dopóki nie zobaczyliśmy ilości narzędzi współpracujących z konwencjonalnymi commitami, jak możliwość automatycznego generowania change-logu.

Czym jest git-cliff?

Git-cliff_ nie jest_ narzędziem do testowania zgodności z specyfikacją conventional commits. Jest to narzędzie do generowania change-logu, które może wykorzystać historię git do wypełnienia szablonu. Jednakże, ponieważ wspiera i rozróżnia commity konwencjonalne i niekonwencjonalne, ma potencjał do tego, aby służyć nam właśnie w tym celu. Narzędzie jest zbudowane w języku Rust i używa powiązań do libgit2, aby pobierać commity z repozytorium, więc nie potrzeba mieć nawet zainstalowanego samego programu git. Skompresowany obraz dockerowy, który jest z nim dostarczany, jest nawet (nieco) mniejszy niż ten dla alpine/git. Ponieważ w maal planujemy teraz generowanie change-logów z naszych commitów, możliwość użycia jednej aplikacji zarówno do ich weryfikacji, jak i renderowania change-logu ograniczyłaby ilość zależności w naszym procesie deweloperskim.

Po co sprawdzać wiadomości commitów akurat przez pipeline CI?

Zawartość wiadomości commitów można sprawdzać na różne sposoby, w tym:

za pomocą hooków git po stronie klienta,
za pomocą hooków git po stronie serwera,
podczas przeglądu kodu,
oraz narzędziami dedykowanymi do CI.

Kiedy mówimy o procesie, który dotyczy każdego commitu, warto rozważyć koszty i korzyści z każdego podejścia.

Jeśli możesz kontrolować lub zautomatyzować środowisko deweloperskie swojego zespołu, to użycie hooków git po stronie klienta prawdopodobnie będzie najmniej kosztowną opcją. Skrypty te mogą być uruchamiane przed utworzeniem commitu, oszczędzając zdalnemu serwerowi git lub serwerowi CI zbędnych obliczeń oraz ucząc deweloperów dyscypliny za pomocą natychmiastowych informacji zwrotnych. Nie są one instalowane przy klonowaniu repozytorium, wbrew temu, co niektórzy mogliby oczekiwać, i mogą być dodawane i usuwane przez deweloperów w dowolnym momencie, co oznacza, że wymuszenie ich stosowania za pomocą podejścia odgórnego w organizacji wymaga dodatkowych narzędzi. Istnieją świetne rozwiązania, które integrują instalację hooków z lokalnymi narzędziami do budowy oprogramowania, takimi jak husky dla npm i jego reimplementacje dla innych języków jak np. cargo-husky. Jednakże, w maal jeszcze nie zdecydowaliśmy się na rozwiązanie, które wymusiłoby wspólne środowisko deweloperskie i każda nowa zależność deweloperska komplikuje proces wdrożenia do projektu, więc postanowiliśmy spróbować czegoś innego.

Hooki git po stronie serwera mogą z kolei wymagać pewnej kontroli nad serwerem hostującym repozytorium git. W przypadku serwera Gitea, na przykład, zarządzanie nimi na poziomie repozytorium jest stosunkowo proste, ale jeśli nie planujesz używać tylko skryptów shell do weryfikacji commitów (czego my nie chcemy) będziesz musiał zainstalować coś na maszynie lub obrazie dockerowym, na którym działa serwer git. Może to być naprawdę dobry pomysł, jeśli nie masz żadnej dedykowanej infrastruktury CI. Ponieważ my już mamy łatwo konfigurowalne narzędzia CI, postanowiliśmy trzymać się ich i nie wprowadzać złożoności w nowym obszarze infrastruktury.

Interfejs do zarządzania hookami po stronie serwera w ustawieniach repozytorium na platformie Gitea.

Podobnie, używanie code review do sprawdzania czegoś, co może być łatwo zweryfikowane przez maszynę, mogłoby niepotrzebnie zwiększyć napięcie między deweloperami w okresie adaptacji. Jeśli Twój zespół deweloperski nie składa się z kilku bardzo zdyscyplinowanych osób, to podejście będzie również najbardziej kosztowne.

Wreszcie, korzystanie z CI zazwyczaj pozwala znacznie łatwiej osiągnąć rozdzielenie konfiguracji użytkowników, repozytoriów i serwera. W przeciwieństwie do hooków git, konfiguracja CI może być kontrolowana wersjami. Wadą jest to, że zawsze będzie to obliczeniowo droższe niż hooki po stronie klienta, a informacje zwrotne mogą nie być tak szybkie.

Biorąc pod uwagę wcześniejsze praktyki w firmie maal i narzędzia, którymi dysponowaliśmy, użycie CI do tego zadania było dla nas najbardziej naturalnym wyborem.

Rozwiązanie, które wybraliśmy

W firmie maal używamy Drone-CI do naszych pipeline’ów, więc całe nasze rozwiązanie będzie zawarte w dwóch plikach zapisanych w naszym repozytorium:

.drone.yml - definiujący kroki CI wykonujące komendy git-cliff
cliff.toml - zawierający konfigurację dla git-cliff

Pisanie szablonu generującego błąd

Ponieważ git-cliff jest przede wszystkim narzędziem do generowania change-logów, nie posiada on żadnej oczywistej opcji konfiguracyjnej, która pozwoliłaby natychmiast zakończyć działanie z błędem w przypadku commitu, który nie spełnia standardów conventional commits. Jednakże ma on system szablonów, który można zaadaptować, aby zwracał w takim wypadku błąd. Git-cliff używa języka Tera do swoich szablonów, która oferuje prostą funkcję throw. Oto minimalistyczny szablon, z jej użyciem, który zwróci błąd przy źle sformatowanej wiadomości:

[changelog]
# template for the changelog body
body = """
{% for commit in commits %}
    {% if not commit.conventional %}
        {{ throw() }}
    {% endif %}
{% endfor %}
"""

Jednak aby to działało zgodnie z oczekiwaniami, musimy najpierw upewnić się, że dodaliśmy do naszej konfiguracji dwie opcje:

[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = false

Dodanie conventional_commits = true sprawia, że narzędzie analizuje commity zgodnie ze specyfikacją. W przeciwnym razie nie próbowałoby ono rozpoznawać części wiadomości zawierającej typ.
Ustawiając filter_unconventional na false, informujemy narzędzie, aby umieściło również „niekonwencjonalne” commity w szablonie, co da mu szansę na wyrzucenie błędu. W przeciwnym razie git-cliff zignoruje commity, które nie są konwencjonalne, bez zgłoszenia błędu z szablonu.

Mając tylko te zawartości w pliku cliff.toml i uruchamiając git-cliff w jednym z naszych repozytoriów, w którym chcemy wprowadzić konwencjonalne commity, uzyskamy:

git-cliff
 ERROR git_cliff > Template render error:
Function call 'throw' failed  
Function `throw` was called without a `message` argument

To jest oczekiwane zachowanie, biorąc pod uwagę, że repozytorium jest pełne commitów, które nie spełniają specyfikacji. Polecenie zwróciło kod wyjścia równy 1, co jest dla nas świetne, ponieważ sprawi, że pipeline Drone CI odrzuci kod. Jednak commity niekonwencjonalne raczej prędko nie znikną z naszej historii, co oznacza, że kod będzie odrzucany za każdym razem.

Wstrzykiwanie kontekstu do błędu

Zanim ustalimy, jak skonfigurować CI, aby git-cliff sprawdzał tylko kod w pull requestach, możemy nieco poprawić komunikat błędu. Możemy dodać wiadomość do wywołania funkcji throw i zbudować ciąg wejściowy, uwzględniając inne pola commitów dostępne w kontekście szablonu.

[changelog]
body = """
{% for commit in commits %}
    {% if not commit.group or not commit.conventional %}
        {{ throw(message=
          "Invalid commit format of commit:"
          ~ commit.id
          ~ "\nMessage: "
          ~ commit.message
          ~ "does not adhere the conventional commits specification."
        ) }}
    {% endif %}
{% endfor %}
"""

Teraz, gdy uruchomimy program, otrzymujemy więcej szczegółów na temat tego, co poszło nie tak:

git-cliff
 ERROR git_cliff > Template render error:
Function call 'throw' failed
Invalid commit format of commit: 834b6b5df53395132e79bcd54c80a1f83778f29b
Message: Merge branch 'branch1' of ssh://remote-url into branch2
does not adhere the conventional commits specification.

Zwróć uwagę, że do tego wymagana jest co najmiej wersja 2.2.0 programu git-cliff,a w tym samouczku używamy wersji 2.2.2.

Ignorowanie merge commits

Rozszerzając komunikat o błędzie, odkryliśmy, że merge commits mogą powodować pewne problemy, które na szczęście możemy rozwiązać, rozszerzając nasz plik cliff.toml o commit parser:

[git]
conventional_commits = true
filter_unconventional = false
# parsing commits before they are put in the template context
commit_parsers = [
    { message = "^Merge branch", skip = true }
]

Parsery przetwarzają commity przed ich umieszczeniem w kontekście szablonu. Mogą też zrobić znacznie więcej niż tylko pomijanie commitów na podstawie wzorca regex.

Po wyeliminowaniu merge commits powinniśmy pozostać tylko z leniwymi wiadomościami, z którymi chcemy walczyć:

git-cliff
 ERROR git_cliff > Template render error:
Function call 'throw' failed
Invalid commit format of commit: f1ab72c9048eeea52f9a190c4adf97b0a1501e2d
Message: quickfix
does not adhere the conventional commits specification.

Ach, tak.

quickfix

Ewidentnie ktoś chciał jak najszybciej skończyć pisanie tej wiadomości.

Używanie git-cliff z Drone CI do sprawdzania pull requestów

Aby w pełni uświadomić sobie problemy związane z naszymi złymi commitami z przeszłości, uruchommy git-cliff na serwerze pipeline CI. Możemy stworzyć nowy dedykowany pipeline do tego zadania w naszym pliku .drone.yml, używając obrazu git-cliff przechowywanego w Github Container Registry:

kind: pipeline
type: docker
name: parse_commits

steps:
  - name: render_changelog
    image: ghcr.io/orhun/git-cliff/git-cliff:2.2.2
    pull: if-not-exists
    commands:
      - git-cliff

trigger:
  event:
    - pull_request

git commit -m "ci: make sure that commit messages follow conventional commits spec"

Pipeline nie przechodzi, choć z powodu innego commitu, przy czym problem jest zasadniczo ten sam. Zamiast cieszyć się z wdrożenia konwencjonalnych commitów, zablokowaliśmy nasze pull requesty.

Aby ostatecznie uwolnić się od naszej złej przeszłości, możemy użyć kilku zmiennych środowiskowych ustawionych przez Drone CI, konkretniei:

Musimy jednak być ostrożni, ponieważ tutaj w maal podczas naszych eksperymentów odkryliśmy, że wartość DRONE_COMMIT_BEFORE nie zawsze jest ustawiona. Chociaż a coś w stylu ..bc8abbf9f5d0304ad1aef059fa59e72554363f5f będzie dalej rozumiane przez git-cliff jako zakres, nie uwzględni commitów, które chcemy brać pod lupę w danym momencie. Aby obejść ten problem, stworzymy bardzo krótki skrypt używając POSIX shell (który jest jedyną powłoką dostępną w naszym obrazie docker) dla naszego kroku pipeline.

steps:
  - name: try_render_changelog
    image: ghcr.io/orhun/git-cliff/git-cliff:2.2.2
    pull: if-not-exists
    commands:
      - >
        if [ -z ${DRONE_COMMIT_BEFORE:-""} ];
          then git-cliff ${DRONE_COMMIT_AFTER}~1..${DRONE_COMMIT_AFTER};
          else git-cliff ${DRONE_COMMIT_BEFORE}..${DRONE_COMMIT_AFTER};
        fi

Czytając rozwiązanie, które przedstawiliśmy, pamiętaj, że Drone wykonuje pewne podstawienia zmiennych w pliku przed wykonaniem poleceń. W rezultacie otrzymujemy następujące uruchomienie:

Minimalizowanie czasu trwania pipeline’u

Drone rozpoczyna każdy pipeline od “ukrytego” kroku, który wykonuje clone za pomocą dostarczonego przez Drone obrazu dockera z gitem. Wykonuje on najprostszy git clone, co oznacza, że pobiera całe repozytorium ze wszystkimi plikami, tylko po to, aby w naszym przypadku sprawdzić, to co jest zasadniczo jedynie logiem z gita. Możemy znacznie poprawić wydajność pipeline’u, wyłączając ten krok i dostarczając własną implementację, która wykonuje git clone, pobierając tylko historię commitów i jeden plik: cliff.toml.

Oto ostateczna konfiguracja pipeline’u:

kind: pipeline
type: docker
name: parse_commits

clone:
    disable: true

steps:
  - name: git_clone_history_only
    image: bitnami/git
    pull: if-not-exists
    commands:
      - git clone --filter=blob:none --filter=tree:0 --sparse --no-checkout --quiet ${DRONE_GIT_HTTP_URL} .
      - git checkout ${DRONE_COMMIT} -- cliff.toml
  - name: try_render_changelog
    image: ghcr.io/orhun/git-cliff/git-cliff:2.2.2
    pull: if-not-exists
    commands:
      - >
        if [ -z ${DRONE_COMMIT_BEFORE:-""} ];
          then git-cliff ${DRONE_COMMIT_AFTER}~1..${DRONE_COMMIT_AFTER};
          else git-cliff ${DRONE_COMMIT_BEFORE}..${DRONE_COMMIT_AFTER};
        fi

trigger:
  event:
    - pull_request

Używamy kilku trików, aby zminimalizować klonowanie:

git clone --filter=blob:none zapobiega pobieraniu jakiejkolwiek zawartości plików podczas klonowania. Nie będziemy potrzebować żadnych plików poza cliff.toml, który pobieramy w następnym kroku.
git clone --filter=tree:0 jest podobne do git clone --sparse, ponieważ ogranicza głębokość drzewa plików, które są pobierane.
git clone --no-checkout zapobiega klonowaniu domyślnej gałęzi repozytorium.
git checkout ${DRONE_COMMIT} -- cliff.toml pobiera zawartość jedynego pliku, na którym nam zależy, czyli konfiguracji dla git-cliff w najnowszej wersji dla danego PR.

Dzięki tym trikom udało nam się skrócić czas trwania pipeline’u o połowę - z około 20 sekund do 11 sekund.

Wykorzystanie git-cliff w pełni możliwości

Teraz, gdy skonfigurowaliśmy git-cliff jako narzędzie do lintowania wiadomości commitów, możemy rozszerzyć szablon i wykorzystać jego output do innych celów. Możemy stworzyć pipeline release’ów oparty na pull requestach do wybranej gałęzi, z change-logami generowanymi z commitów. Możemy również skonfigurować CI tak, aby dodawał komentarze do pull requestów z estetycznie sformatowanym podsumowaniem. W zasadzie istnieje cały aspekt “generatora change-logów”, którego tutaj nie omówiliśmy, ale więcej na ten temat możesz dowiedzieć się z dokumentacji git-cliff.

Zarządzanie firmą i systemy ERP

E-commerce

Hosting i infrastrukura IT

Web app development

Doradztwo IT

Ucz się z nami z naszego TechBloga

TechBlog