Conventional commits

En "conventional commit" är ett enkel regelverk för att alla inom teamet ska följa samma åtagande vid en commit. Detta gemensamma regelverk gör det möjligt att bygga automatiska "change logs", möjlighet att hämta ut statistik baserat på TYPE eller SCOPE och skapar förutsättningar för standardiseringar.

Grundförståelse

Vi utgår i grunden från Conventional Commits Länk till annan webbplats. men med lite modifikationer.

En "conventional commit" består av fyra komponenter.

• TYPE = Använd endast någon av nedan definierade typer av commits

• SCOPE = Ange den funktion/komponent som ingår i commiten

• DESCRIPTION = Skriv på engelska i imperfekt

• BODY = Skriv på svenska i imperfekt

• FOOTER = Innehåller info om breaking changes och / eller hänvisningar till issues (eller work items i ex. DevOps) med #ID (exempelvis #10000)

Typer av commits

Nedan listas de typer vi använder plus en kort förklaring.

feat = Ny funktionalitet för användare

fix = Åtgärd av bugg för användare

perf = Åtgärd för prestanda

revert = Tillbaka till en föregående commit

docs = Uppdaterad dokumentation

style = Formatering av kod

chore = Nödvändiga ändringar i projektet

refactor = Ombyggnad av befintlig kod

test = Lägga till eller justera tester

build = Justeringar i byggprocessen, dependencies m.m.

ci = Justeringar i Continuous Integration processen

Standard commit

En standard commit innehåller de fyra komponenterna i denna ordning.

TYPE(SCOPE): DESCRIPTION

BODY

FOOTER

OBS! Längden på DESCRIPTION bör inte vara mer än 50 tecken och längden på BODY bör inte överstiga 120 tecken.

Commit för release

En commit som taggas för release ser ut som följande och bör i möjligaste mån göras per automatik, vi använder oss av semantic-release (se mer under Tooling)

chore(release): SEMVER [skip ci]

OBS! SEMVER ska ersättas av aktuellt versionsnummer, ex 3.2.1

Pusha en commit

För VsCode finns ett plugin som fungerar som hjälpmedel för att få med sig type, scope, description, body och footer: Conventional Commits Länk till annan webbplats.. Detta gör det också möjligt att dela scopes i ett repo i en VsCode workspace-fil. Notera att för att emojis ska fungera på bl.a. DevOps krävs inställningen "Emoji Format" att vara inställd till "emoji".

Pushar man via terminal kan man använda nedan git-kommando:

git commit -m "TYPE(SCOPE): DESCRIPTION" -m "BODY" -m "FOOTER"

Skrivregler

Både type och scope skrivs på engelska med gemener.

Description och body skrivs på svenska med initial versal och i övrigt gemener.

Referera issues

För att hänvisa en issue (eller work item i ex. DevOps) skriver man ett hash-tecken följt av dess nummer i footern, exempelvis #10000

Exempel på korrekt skriven commit

Nedan följer ett konkret exempel på en commit som följer vårt gemensamma regelverk

Inline terminalkommando (varje uppdelad -m blir en egen rad):

git commit -m "fix(footer): Fixed non-working mailto link" -m "Länken för mailto hade ett kommatecken för mycket och kunde inte öppnas i mejlklienten" -m "#10000"

Som fulltext (i exempelvis vi / nano, notera radbrytningarna. En tom rad används för att bryta de olika segmenten):

fix(footer): Fixed non-working mailto link

Länken för mailto hade ett kommatecken för mycket och kunde inte öppnas i mejlklienten

\#10000

Notera backslashet i footern för att escape:a hashet så det inte blir en kommentar.

Breaking changes

Om en commit innehåller breaking changes, dvs att andra projekt som är beroende också behöver uppdateras så ska det finnas en "BREAKING CHANGE: " text i FOOTERN.

Exempelvis:

feat(api): renamed field 'name' to 'title'

API-svaret returnerar nu 'title' istället för 'name'

BREAKING CHANGE: I och med ändringen av fältet 'name' till 'title' måste man parera denna ändring i frontend.

Automatiska releaser

En av de främsta fördelarna med att använda sig av Conventional Commits är att det ger förutsättningar för automation. Med verktyg som semantic-release Länk till annan webbplats. kan hela hanteringen av versionering skötas automatiskt.

Automatiska changelogs

Utöver releaser så kan man också få helt automatiska changelogs baserat på githistoriken, och det är därför vi är så pass detaljerade i våra commits med tydliga body-texter.

Tooling

Nedan följer vår rekommenderade setup för våra repos.

semantic-release

I våra repos använder vi semantic-release Länk till annan webbplats. för att automatiskt hantera taggning för releaser.

Detta kombineras med @semantic-release/changelog Länk till annan webbplats. (och semantic-releases inbyggda release-notes-generator) för att automatiskt generera ändringsloggar. Eftersom vi har som mål att erbjuda ändringsloggar som är läsbara för organisationen och inte bara utvecklare har vi även en egen preset för detta: conventional-changelog-regionhalland Länk till annan webbplats.. Denna preset använder commit-body istället för subject i loggen, där vi skriver en mer utförlig beskrivning (se "Exempel på korrekt skriven commit").

Finns ingen commit-body används description som fallback.

För att använda vår preset installerar man den och sedan ställer man in sin semantic-release config med följande parameter för release-notes-generator.

.releaserc:

"@semantic-release/release-notes-generator",

{

"preset": "regionhalland"

}

Vi rekommenderar också Googles plugin till semantic release, @google/semantic-release-replace-plugin Länk till annan webbplats., för att kunna bumpa versionsnummer i samband med semantic-release körningen. På så vis slipper man manuellt uppdatera versionssträngar i projektet, utan de sätts med regex till nästa version, som bestämt av semantic-release.

commitlint

Vi använder oss av commitlint Länk till annan webbplats. för att säkra oss att vi förhåller oss till conventional commits-tänket. Detta kombineras med @commitlint/config-conventional Länk till annan webbplats.

"commitlint": {

"extends": [

"@commitlint/config-conventional"

]

}

husky

Vi använder oss av husky Länk till annan webbplats. i våra repos för att installera en commit-msg hook som automatiskt exekverar commitlint efter man skrivit sin commit.

package.json:

"husky": {

"hooks": {

"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"

}

}