Conventional commits

Grundförståelse

Vi utgår i grunden från Conventional Commits 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 exempelvis 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, exempelvis 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. 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 kan hela hanteringen av versionering skötas automatiskt.

Automatiska changelogs

Utöver releaser 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 för att automatiskt hantera taggning för releaser.

Detta kombineras med @semantic-release/changelog (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. 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, 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 för att säkra oss att vi förhåller oss till conventional commits-tänket. Detta kombineras med @commitlint/config-conventional

"commitlint": {

"extends": [

"@commitlint/config-conventional"

]

}

husky

Vi använder oss av husky 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"

}

}