Automatitza el changelog del teu projecte Laravel amb commits i release-please

Si treballes amb Git i segueixes una convenció clara per als missatges de commit, pots automatitzar la generació del changelog i la creació de noves versions amb etiquetes directament des de GitHub, sense necessitat d’instal·lar res al projecte local.

1. Què fa release-please?

Llegeix els commits del projecte seguint la convenció Conventional Commits.
Genera automàticament un fitxer CHANGELOG.md actualitzat.
Calcula la nova versió segons SemVer (1.0.0, 1.1.0, etc.) a partir dels commits.
Crea automàticament una “release” i una etiqueta (tag) a GitHub.
No modifica el codi local ni el repositori fins que no acceptes el pull request generat.

2. No cal instal·lar res localment

En el nostre cas, no hem instal·lat release-please localment ni hem necessitat un package.json. La configuració es fa directament via GitHub Actions, aprofitant el token que GitHub proporciona automàticament amb permisos per fer els canvis.

3. Configura GitHub Actions

Només cal crear un fitxer de workflow dins la carpeta .github/workflows/ amb un contingut similar a aquest:

# .github/workflows/release-please.yml

name: Release Please

on:
  push:
    branches:
      - main  # o la branca principal que facis servir
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Release Please
        uses: googleapis/release-please-action@v4
        with:
          release-type: php # o el tipus que correspongui
          token: ${{ secrets.GITHUB_TOKEN }}

Amb això, cada cop que facis un push a la branca main, GitHub Actions crearà o actualitzarà automàticament un pull request amb el changelog i la nova versió calculada.

4. Segueix la convenció Conventional Commits

Perquè release-please funcioni correctament, és important que els teus commits segueixin la convenció feat:, fix:, chore:, etc. Exemples:

feat: afegir suport per notificacions
fix: corregir bug en validació
chore: actualitzar documentació

Així, la eina pot determinar si cal incrementar la versió major, menor o patch i quins canvis afegir al changelog.

5. Fluix de treball

Tu fas commits localment amb missatges semàntics i fas push a GitHub.
GitHub Actions s’activa, llegeix els commits, actualitza el changelog i crea un pull request.
Revises el pull request i l’integrem al branch principal manualment per controlar la publicació.
GitHub crea automàticament la release i etiqueta la versió.

6. Avantatges

No has de mantenir el changelog manualment ni preocupar-te de versions locals.
El procés està completament automatitzat i integrat a GitHub.
Control total perquè la versió i el changelog només es publiquen quan acceptes el PR.
Perfecte per projectes que no tenen package.json o entorns on no vols instal·lar dependències locals.

7. Com gestionar la versió si el projecte la necessita dins d’un fitxer

Hi ha casos en què el projecte requereix que la versió aparegui dins d’un fitxer específic. És habitual, per exemple, en plugins o temes de WordPress, on el fitxer principal PHP o un CSS han d’incloure una línia com Version: 1.0.

Si no vols gestionar tu manualment aquest número, pots deixar-lo amb un valor neutral com Version: 0.0.0 i fer servir un fitxer de configuració addicional perquè release-please actualitzi automàticament aquest valor quan es genera una nova versió.

Només cal crear un fitxer release-please-manifest.json a l’arrel del repositori amb aquest contingut:

{
  "ruta/plugin.php": {
    "release-type": "php"
  }
}

Substitueix rutaplugin.php pel nom real del fitxer que conté la versió. Això indica a release-please que aquest fitxer ha de ser modificat automàticament per reflectir la nova versió en cada release. I a continuació una llista dels valors per a release-type acceptats:

node: Projectes amb package.json (Node.js/NPM)
python: Projectes Python amb setup.py o pyproject.toml
go: Projectes Go amb mòduls
java: Projectes Java amb Maven/Gradle
php: Projectes PHP genèrics
simple: Projectes senzills sense fitxers de versió específics
generic: Similar a simple, però sense cap estructura específica
ruby: Projectes Ruby
docker: Projectes amb Dockerfile
terraform-module: Mòduls Terraform

Aquesta tècnica també es pot aplicar a altres fitxers com style.css en temes de WordPress o qualsevol altre fitxer que contingui la versió explícita en el seu contingut.

8. Accions a GitHub

Assegura’t que a la configuració del repositori a GitHub, a Settings > Actions > General > Workflow permissions, està activada l’opció:

Read and write permissions" (no només lectura).

I marcada la casella:

Allow GitHub Actions to create and approve pull requests

IMPORTANT

Tot i ser admin, el token pot tenir restriccions per crear labels. Per tant, hem de crear manualment els labels que necessita Release Please:

Ves a la pestanya Issues del teu repo.
Fes clic a Labels.
Crea aquests labels (pots copiar i enganxar):
- release-please:pending
- release-please:tagged
- autorelease: pending
- autorelease: tagged

No cal posar-los a cap color concret ni assignar-los a cap issue.
Si, tot i això, per un tema de permisos no realitzes el workflow, podràs crear un PAT.

8. Entén com funciona el procés de Release Please

Release Please no fa el merge automàtic a main. En lloc d’això, crea un Pull Request (PR) amb el CHANGELOG.md actualitzat i la nova versió.

Què has de fer ara?

Ves a la pestanya “Pull requests” del teu repositori a GitHub.
Busca un PR obert creat per release-please[bot] (normalment amb un títol tipus chore(main): release 1.2.3).
Revisa el contingut del PR.
Fes merge d’aquest PR quan estigui llest.

Resum

No esperis que el CHANGELOG.md es modifiqui directament després d’un push.
Release Please crea un PR amb els canvis; només s’aplicaran al main quan facis el merge.
Si no es crea cap PR, revisa els logs de l’Action per detectar errors o missatges d’avís.

9. Què passa si elimines el CHANGELOG local?

No passa res: quan GitHub Actions s’executi, generarà el changelog des de zero llegint tots els commits, així que el tindràs sempre actualitzat i coherent amb la història del teu repositori.

—

Amb aquesta configuració, ja tens un flux net i automàtic per gestionar versions i changelogs usant release-please i GitHub Actions, sense necessitat de res local i amb tota la potència del sistema de gestió de versions de GitHub.