Automatitza el changelog del teu projecte Laravel amb commits i standard-version

Automatitzar el changelog a partir dels commits és una pràctica molt útil per mantenir un registre clar i actualitzat dels canvis del teu projecte sense haver d’escriure-ho manualment cada vegada. Si treballes amb Laravel + Vite i Git, en aquest post t’explico com fer-ho fàcilment usant la convenció de commits i l’eina standard-version.

1. Per què automatitzar el changelog?

• Evites errors o oblidar detalls importants.
• Tens un historial clar dels canvis, agrupats per tipus (features, fixes, docs…).
• Facilita la comunicació amb l’equip i usuaris finals.
• Generes etiquetes i versions semàntiques automàticament.

2. Utilitza la convenció de commits

Perquè la generació automàtica funcioni, és important escriure els commits seguint un format estàndard, per exemple el de Conventional Commits. Alguns exemples:

• feat: afegir autenticació d’usuaris
• fix: corregir error en el formulari de registre
• docs: actualitzar README
• chore: actualitzar dependències

3. Instal·la standard-version

A la carpeta del teu projecte (on tens el package.json):

npm install --save-dev standard-version

4. Afegir script per generar el changelog

Afegeix al teu package.json la següent línia a l’apartat scripts:

{
  "scripts": {
    "release": "standard-version"
  }
}

5. Genera el changelog i etiqueta una versió nova

Quan vulguis crear una nova versió i generar automàticament el changelog, només cal executar:

npm run release

Això farà que es creï o actualitzi el fitxer CHANGELOG.md i es generi una etiqueta Git amb la nova versió segons el tipus de commits que tinguis.

6. Opcional: ajuda per escriure commits amb convenció

Per ajudar-te a escriure commits que compleixin la convenció, pots utilitzar commitizen amb la configuració cz-conventional-changelog:

npm install --save-dev commitizen cz-conventional-changelog

Afegir al package.json:

{
  "scripts": {
    "commit": "cz"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}

Així, per fer un commit guiada, només cal executar:

npm run commit

7. Integra-ho en el teu workflow

• Pots executar npm run release manualment quan facis un llançament.
• O bé automatitzar-ho amb un GitHub Action o una altra eina CI/CD perquè es generi i etiqueti automàticament quan facis push a la branca principal.

8. Automatitza la generació del changelog amb GitHub Actions

Per automatitzar la generació del changelog i la creació de la nova etiqueta quan fas push a la branca main (o master), pots afegir un workflow de GitHub Actions així:

# .github/workflows/release.yml

name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Generate release and changelog
        run: npm run release

      - name: Push changes and tags
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: 'chore(release): automatic release by GitHub Actions'
          tag_prefix: ''
          tag: true
          branch: main

Amb aquest workflow:

• Quan facis push a main, s’instal·len les dependències.
• Es genera el changelog i la nova etiqueta (versionat).
• Es fan push automàticament els canvis (CHANGELOG.md i etiqueta) a la branca principal.

Assegura’t que el repositori té permisos per fer push des de GitHub Actions. Si el teu repositori és privat, pot ser que hagis de configurar un token d’accés.

—

Així tens un procés complet, des de l’escriptura dels commits fins a la generació i publicació automàtica del changelog i les versions.