El mòdul anterior va acabar amb un diagnòstic incòmode: l'equip de gestor-tasques ja té un procés impecable —forks, pull requests, revisions, branques protegides, integració contínua— i tot i així pot acabar amb un historial que ningú sigui capaç de llegir. Comencem a corregir-ho pel punt més quotidià i més descurat de tots: el missatge de confirmació.

Aquesta lliçó salda per fi dos deutes del curs. A la lliçó 02-04 vam aprendre a confirmar canvis amb git commit -m i vam dir que les convencions de missatges arribarien aquí. A la lliçó 06-01 vam escriure un hook commit-msg que exigia un tiquet amb format GT-NNN, però validàvem una convenció que encara no havíem explicat. I a la 07-06 vam validar aquesta mateixa convenció al CI. És el moment d'explicar d'on surt tot això.

Convé entendre la magnitud de l'assumpte abans de començar. Un desenvolupador escriu entre cinc i vint missatges de confirmació al dia. Són l'únic text en prosa que produeix el projecte de manera sistemàtica, l'únic que sobreviu als refactors i l'únic que hi serà quan l'autor original ja no sigui a l'empresa. El codi diu què fa el programa; l'historial és l'únic lloc on pot quedar escrit per què ho fa així.

1. Per a qui s'escriu un missatge de confirmació
2. El perquè importa més que el què
3. Anatomia d'un bon missatge
4. La línia d'assumpte: les set regles
5. El cos: motivació i context
6. El peu: referències, tiquets i coautoria
7. Missatges dolents i la seva versió bona
8. Conventional Commits
9. BREAKING CHANGE i la versió derivada
10. Plantilles amb commit.template
11. Escriure a l'editor, no amb -m
12. Fer complir la convenció: hook i CI
13. L'idioma del missatge

Hi ha una resposta intuïtiva i equivocada: "per a mi, per recordar què vaig fer". És equivocada perquè tu, d'aquí a una setmana, ja no necessitaràs el missatge: tindràs el context fresc. El missatge existeix per a tres lectors que no el tenen.

Lector 1: el teu jo d'aquí a dos anys. No recorda res del context. No recorda la reunió on es va decidir allò, ni el client que es va queixar, ni la limitació del navegador que va obligar a fer una cosa estranya. El commit és l'únic que queda.

Lector 2: qui executi git blame sobre una línia estranya. És el cas més freqüent i el més valuós. Algú troba a app.js una condició absurda:

El seu primer impuls serà esborrar-la. A la lliçó 06-03 vam veure que git blame respon quin commit va introduir aquella línia. Si aquell commit diu apanys, el lector esborrarà la condició i reintroduirà la fallada. Si diu Evita el filtre per data a Safari 14: el seu Intl.DateTimeFormat retorna la zona horària en un format que trenca l'anàlisi, no l'esborrarà. La qualitat del missatge decideix si la fallada torna.

Lector 3: qui revisi la teva pull request. A la lliçó 07-02 vam veure que revisar bé exigeix entendre la intenció abans que el diff. Una PR amb commits atòmics i ben descrits es revisa commit a commit i en la meitat de temps. Una PR amb vuit commits anomenats wip, wip2 i ara sí obliga el revisor a llegir un diff gegant sense cap guia.

Hi ha un quart lector que a més és una màquina: les eines que generen changelogs, dedueixen versions i filtren l'historial. D'això tracta l'apartat 8.

Aquesta és la idea central de tota la lliçó, i la que més costa interioritzar.

El diff ja diu el què. Hi és, complet, exacte i per sempre. git show te'l mostra amb precisió de caràcter. Un missatge que diu Canvia el color del botó a blau quan el diff diu - color: #c00; / + color: #06c; és redundant: no aporta ni un bit d'informació nova.

El que el diff no pot dir mai:

Compara aquests dos missatges sobre exactament el mateix diff de gestor-tasques:

El primer és informació que ja era al diff. El segon conté quatre fets que no són en cap altra banda del repositori: d'on venia el valor vell, quina fallada concreta provocava, com es va triar el nou i per què no és més gran. D'aquí a dos anys, quan algú proposi tornar-lo a abaixar "perquè 30 segons és una barbaritat", aquell missatge és la resposta.

La regla: si el teu missatge es pot deduir llegint el diff, encara no has escrit el missatge.

Git no imposa cap format, però sí que tracta el text de manera estructurada, i gairebé totes les eines de l'ecosistema assumeixen la mateixa convenció. L'estructura canònica té tres parts:

La línia en blanc entre l'assumpte i el cos no és estètica: és sintaxi. Git fa servir la primera línia com a assumpte a git log --oneline, al %s de --pretty, a l'assumpte dels correus de git format-patch i al títol per defecte d'una pull request. Si te la saltes, el missatge sencer es converteix en assumpte:

Tot el text enganxat, i el --oneline inservible.

No és una xifra màgica arbitrària: és el límit pràctic perquè git log --oneline, la llista de commits d'una plataforma i el git shortlog càpiguen en una línia sense truncar-se. Les plataformes d'allotjament tallen visualment al voltant dels 72 caràcters, i GitHub avisa a partir de 50.

Si no cap en 50 caràcters, gairebé sempre és una d'aquestes dues coses: el commit fa massa coses (ho veurem a la lliçó 08-02) o estàs posant a l'assumpte allò que va al cos.

Escriu com si donessis una ordre al repositori. La prova infal·lible és completar aquesta frase:

"Si s'aplica, aquest commit _______"

No és caprici: el mateix Git escriu així. Merge branch 'x', Revert "...", Initial commit. Si els teus missatges fan servir un altre temps verbal, l'historial barreja dues veus.

És un títol, no una frase. I en 50 caràcters, un caràcter compta.

Llevat que facis servir Conventional Commits (apartat 8), on la convenció habitual és minúscula després dels dos punts. Tria'n una i sigues coherent.

Corregeix l'error no diu res. Corregeix l'esborrat de tasques amb adjunt sí.

Canvia app.js és inútil: git log --stat ja ho diu. L'àmbit, si cal, va amb la sintaxi de Conventional Commits.

Afegeix el filtre per etiqueta i corregeix el marge del peu descriu dos canvis independents. La lliçó 08-02 desenvolupa aquesta idea a fons.

El cos és opcional per a un canvi trivial i obligatori per a qualsevol canvi no obvi. S'ajusta manualment a 72 columnes per una raó molt concreta: git log sagna el cos amb quatre espais, així que 72 + 4 = 76, i cap en un terminal de 80 columnes sense que Git reajusti el text (no ho fa: Git mai no reformata el teu missatge).

Un cos útil respon aquestes preguntes, no necessàriament totes:

1. Quin era el problema o la necessitat? L'estat anterior i per què no servia.
2. Per què aquesta solució? I sobretot, quines alternatives es van descartar.
3. Quins efectes col·laterals té? Rendiment, compatibilitat, migracions.
4. Què NO fa aquest canvi? Delimitar és tan útil com descriure.
5. Què cal saber per revisar-ho? Un enllaç, un mesurament, una ordre de reproducció.

Exemple complet, sobre un canvi real de gestor-tasques que va fer la Carla:

Fixa't en el que aporta i que no és al diff: el mesurament concret, l'alternativa descartada amb el seu motiu, la data de caducitat del codi de migració i el límit explícit del canvi.

El peu (trailer en la terminologia de Git) és un bloc de línies Clau: valor al final del missatge, separat per una línia en blanc. Git l'entén de manera nativa a través de git interpret-trailers, i les plataformes també l'interpreten.

La coautoria mereix una menció especial, perquè resol un problema real de l'equip. Quan l'Ana i el Bruno programen en parella, el commit el signa només qui l'escriu, i git blame (lliçó 06-03) ho atribueix tot a aquella persona. Amb el trailer, les plataformes reconeixen els dos:

Detall important: la línia Co-authored-by ha d'anar al final, precedida d'una línia en blanc, i el correu ha de ser el que la persona té registrat a la plataforma. Si no, el nom apareix però no s'enllaça amb el compte.

Ho pots automatitzar amb git interpret-trailers:

Aquesta taula recull missatges reals de l'historial primerenc de gestor-tasques, quan l'equip encara no tenia convenció, al costat del que haurien hagut de ser.

Fixa't en el patró: els missatges dolents gairebé sempre són curts per pressa o dependents d'un context que s'evapora ("ahir", "el que va comentar la Carla", "ara sí").

Fins aquí hem parlat de prosa per a humans. Conventional Commits és una convenció que a més fa l'assumpte llegible per màquines, sense perdre llegibilitat humana. És la que fa servir el hook commit-msg que vam escriure a la lliçó 06-01.

El format:

Exemples sobre gestor-tasques:

L'àmbit entre parèntesis és lliure i el defineix cada projecte. A gestor-tasques l'equip va acordar: filtres, sync, llista, ui, css, readme, deps, ci. Un àmbit estable converteix git log --oneline | grep '(sync)' en una consulta útil.

1. Filtrar l'historial és trivial. git log --oneline --grep '^feat' et dona totes les funcionalitats noves.
2. Changelog automàtic. Eines com git-cliff, standard-version o semantic-release agrupen els commits per tipus i generen CHANGELOG.md sense intervenció humana.
3. Versió SemVer derivada. Això enllaça directament amb la lliçó 05-05: allà vam acordar MAJOR.MINOR.PATCH i etiquetes anotades, però decidíem el número a mà. Amb Conventional Commits, el número es dedueix de l'historial.
4. Disciplina de granularitat. Si no saps quin tipus posar-hi, gairebé sempre és perquè el commit fa més d'una cosa.

Suposa que des de v1.4.0 l'historial de gestor-tasques conté:

Hi ha un feat i cap BREAKING CHANGE, així que la versió següent és v1.5.0. Si només hi hagués hagut fix, seria v1.4.1. Si no hi hagués hagut ni feat ni fix, no hi hauria versió a publicar.

Un trencament de compatibilitat és un canvi que obliga qui consumeix el teu codi a fer alguna cosa. En SemVer puja el número MAJOR, i és l'únic cas en què la deducció automàtica no pot fallar sense conseqüències greus.

Es marca de dues maneres equivalents:

Forma 1 — amb ! després del tipus o de l'àmbit:

Forma 2 — amb un trailer al peu (permet explicar la migració):

La segona és netament millor: el missatge inclou la guia de migració, i les eines de changelog la copien tal qual a la secció de trencaments. Fes servir les dues alhora si vols que el ! sigui visible a --oneline.

Compte amb el condensat. Si integres les pull requests amb squash merge (ho veurem a fons a la lliçó 08-02), el missatge que compta per a la deducció és el del commit condensat, no els de la branca. Un BREAKING CHANGE amagat al tercer commit d'una branca desapareix si el títol del squash és feat: millores diverses. És un argument fort per revisar el títol del squash abans de fusionar.

La manera més barata que tot un equip escrigui missatges millors és posar-los el recordatori davant dels ulls en el moment exacte. Això fa commit.template: un fitxer el contingut del qual precarrega l'editor cada vegada que confirmes.

Crea el fitxer al repositori, perquè l'Ana, el Bruno i la Carla facin servir el mateix:

Contingut de .gitmissatge:

I s'activa:

Tres detalls que importen:

• Les línies que comencen per # es descarten en desar, així que les instruccions no arriben a l'historial. El caràcter de comentari es pot canviar amb core.commentChar si necessites un # literal (per exemple, per escriure #123).
• commit.template no es versiona sol. El fitxer .gitmissatge sí que és al repositori, però la configuració que l'activa viu a .git/config, que com vam veure a la lliçó 01-05 és local. Documenta el git config --local commit.template .gitmissatge al README.md, o afegeix-lo a l'script d'arrencada del projecte.
• La plantilla no s'aplica amb -m. Només quan Git obre l'editor. Cosa que ens porta a l'apartat següent.

git commit -m "..." és còmode i per això és l'hàbit per defecte de tothom. També és la causa estructural dels missatges dolents, per tres motius:

1. La cometa del terminal et pressiona a ser breu. Escriure un paràgraf entre cometes a la shell és incòmode, així que no l'escrius.
2. No veus el context. L'editor et mostra, comentada, la llista de fitxers modificats. Moltes vegades allà descobreixes que has preparat un fitxer que no volies.
3. No hi ha revisió. Amb -m prems Retorn i ja està. A l'editor llegeixes el que has escrit abans de desar.

Compara:

En executar git commit a seques, l'editor (core.editor, lliçó 01-06) s'obre amb la plantilla i amb això a sota:

I amb -v hi veus a més el diff complet dins de l'editor, que és la millor ajuda possible per escriure el perquè:

Activa-ho sempre:

Quan sí que cal fer servir -m: per a commits veritablement trivials (docs: corregeix una errada), en scripts, i per als --fixup de la lliçó 05-02, que desapareixeran al rebase.

Si el missatge és llarg i prefereixes no dependre de l'editor, hi ha una alternativa neta:

Una convenció que no es comprova s'erosiona en tres setmanes. A la lliçó 06-01 vam escriure un hook commit-msg; ara que la convenció està explicada, aquí tens la versió completa i comentada.

Recorda de la lliçó 06-01 els tres requisits perquè funcioni:

I recorda també l'advertiment, que la lliçó 07-06 va convertir en principi: un hook de client no és un control. git commit --no-verify se'l salta. Per això la mateixa comprovació ha de ser al CI, on no mana ningú:

Un matís important que sempre s'oblida: si la teva política d'integració és squash merge, validar els commits individuals de la branca té poc sentit —desapareixeran— i el que cal validar és el títol de la pull request, que serà l'assumpte del commit condensat. Quina de les dues polítiques convé és exactament la pregunta que resol la lliçó següent.

És una discussió que apareix a tots els equips i que té una única resposta correcta: tria'n un i respecta'l.

El que és veritablement dolent no és triar malament: és no triar. Un historial on s'alternen feat: add tag filter i feat: afegeix el filtre per etiqueta és més difícil de cercar (--grep deixa de funcionar), més difícil de llegir i transmet deixadesa.

A gestor-tasques l'equip va acordar, i ho va escriure al README.md: tipus i àmbit en anglès (perquè són paraules clau de la convenció i les entenen les eines), descripció, cos i trailers en català (perquè és la llengua de treball dels quatre i permet explicar el perquè sense empobrir-lo). És un compromís molt habitual i funciona bé.

El Diego, el col·laborador extern, es va trobar la decisió escrita al README.md del seu fork abans d'obrir la seva primera pull request. Aquest és el lloc on va: al repositori, no al cap de ningú.

Error 1: descriure el què en lloc del perquè. És l'error dominant. Canvia el valor a 30 no aporta res; El valor de 5 s venia del prototip i ja no cobreix l'enviament d'adjunts ho aporta tot. Prova de foc: si el missatge es dedueix del diff, encara no has escrit el missatge.

Error 2: oblidar la línia en blanc després de l'assumpte. Trenca --oneline, els títols de PR i el %s de --pretty. És sintaxi, no estil.

Error 3: context efímer. "Com vam parlar ahir", "el que va demanar la Carla", "segons el correu d'aquest matí". D'aquí a sis mesos no signifiquen res. Escriu el contingut, no el punter.

Error 4: enllaçar a un sistema extern en lloc de resumir. Veure GT-134 et deixa venut el dia que es migri el gestor de tiquets o algú el consulti sense accés. Referencia el tiquet a més de resumir, mai en lloc de.

Error 5: missatges de procés. Canvis demanats a la revisió, Ara sí, Un altre intent. Descriuen la teva jornada, no el codi. Condensa'ls amb --fixup i rebase -i --autosquash (lliçó 05-02) abans de publicar.

Error 6: creure que es pot arreglar després. El missatge d'un commit publicat només es canvia reescrivint l'historial, i això xoca amb la regla d'or de la lliçó 05-01. Un missatge dolent publicat és permanent. (Si encara no l'has enviat, git commit --amend ho arregla; la lliçó 09-02 desenvolupa els casos de desfer.)

Error 7: aplicar Conventional Commits a mitges. Mitja dotzena de commits amb feat: i la resta amb prosa lliure produeix el pitjor dels dos mons: la disciplina de la convenció sense cap dels seus beneficis automàtics, perquè el changelog surt incomplet.

Consell 1: escriu el missatge abans que el codi. Sona estrany i funciona. Si no ets capaç de resumir en una línia el que vas a fer, el canvi encara no està delimitat.

Consell 2: activa commit.verbose avui mateix. git config --global commit.verbose true posa el diff dins de l'editor. És la millora de qualitat més barata de tot el mòdul.

Consell 3: llegeix el teu propi historial un cop al mes. git log --oneline -30. Si no entens els teus commits de fa tres setmanes, tens un problema que creixerà.

Consell 4: fes servir git shortlog -sn --no-merges i git log --oneline --grep. Si les teves consultes a l'historial no retornen res útil, és senyal que els missatges no ho són.

Consell 5: a les revisions, revisa també els missatges. És legítim demanar en una PR "reescriu el missatge del segon commit". És l'única manera que la convenció sobrevisqui.

Consell 6: la plantilla al repositori, no al teu $HOME. Així el Diego la té en clonar el fork.

Per a cadascun d'aquests missatges reals de l'historial primerenc de gestor-tasques, escriu la versió bona: assumpte en imperatiu de ≤50 caràcters i, quan el cas ho demani, un cos. Inventa el context versemblant que falti.

1. fix css
2. actualitza app.js
3. Afegit el cercador i arreglat el marge del peu de pàgina
4. Ara sí que funciona
5. Puja la dependència

En un repositori de proves:

1. Crea un fitxer de plantilla .gitmissatge amb l'estructura de Conventional Commits i activa'l amb commit.template a nivell local.
2. Activa commit.verbose.
3. Instal·la el hook commit-msg de l'apartat 12 a .githooks/ i configura core.hooksPath.
4. Comprova que rebutja apanys diversos, que rebutja feat: afegeix el filtre (falta el tiquet) i que accepta feat(filtres): afegeix el filtre per etiqueta amb Refs: GT-134 al cos.
5. Demostra que --no-verify l'esquiva i explica quina barrera el detindria.

Donat aquest historial des de l'etiqueta v2.3.1 de gestor-tasques:

1. Quina versió SemVer correspon publicar i per què?
2. Escriu el missatge complet del commit 9182b3c amb el seu trailer BREAKING CHANGE i la seva guia de migració.
3. Escriu l'ordre de git log que extrauria només els feat d'aquest rang.
4. Si l'equip integrés aquesta branca amb squash merge i el títol del squash fos feat: millores de sincronització, quina versió deduiria l'eina? Quin problema revela això?

Solució 1:

Solució 2:

--no-verify és una opció del client: no viatja per la xarxa i el servidor no s'assabenta que s'ha fet servir. La barrera que sí que el detura és la del CI (apartat 12) declarada com a comprovació obligatòria en una branca protegida, tal com vam veure a la lliçó 07-06. El hook local és una ajuda per al desenvolupador; la branca protegida és el control.

Solució 3:

1. Correspon v3.0.0. La presència de feat(api)! marca un trencament de compatibilitat, i en SemVer això puja el número MAJOR i posa MINOR i PATCH a zero, independentment que a més hi hagi dos feat i un fix. El trencament mana sempre.

2.

3.

I per localitzar específicament els trencaments, que poden ser al cos:

4. L'eina deduiria v2.4.0 (un feat, cap trencament visible), perquè el BREAKING CHANGE era al cos d'un commit que el condensat va fer desaparèixer. El resultat és greu: es publica com a MINOR un canvi que trenca tots els consumidors, i aquests actualitzen confiant en la garantia de compatibilitat de SemVer.

El que revela és que la política d'integració no és una decisió estètica: canvia quins missatges sobreviuen a la línia principal i, per tant, quina informació queda disponible per a les persones i per a les eines. Si es condensa, el títol del squash s'ha de validar amb el mateix rigor que un commit, i els trailers rellevants s'hi han de propagar. Aquesta política és justament el tema de la lliçó següent.

L'essencial d'aquesta lliçó:

• Un missatge de confirmació s'escriu per a tres lectors sense context: el teu jo d'aquí a dos anys, qui faci blame sobre una línia estranya i qui revisi la teva PR. I per a un quart que és una màquina.
• El diff ja diu el què; el missatge existeix per al perquè. Si el teu missatge es dedueix del diff, encara no l'has escrit. El que només cap al missatge és la motivació, les alternatives descartades, els efectes col·laterals i els límits del canvi.
• L'anatomia és sintaxi, no estètica: assumpte de ≤50 caràcters en imperatiu i sense punt, línia en blanc obligatòria, cos a 72 columnes, i peu amb trailers (Refs, Co-authored-by, BREAKING CHANGE).
• Conventional Commits fa l'assumpte llegible per màquines sense deixar de ser-ho per a les persones: tipus(àmbit): descripció. A canvi d'una disciplina mínima, obtens filtrat de l'historial, changelog automàtic i, enllaçant amb la lliçó 05-05, la versió SemVer derivada del mateix historial.
• Una plantilla amb commit.template al repositori posa el recordatori davant dels ulls en el moment just. I escriure a l'editor amb commit.verbose en lloc de fer-ho amb -m millora la qualitat més que cap altra mesura individual.
• La convenció se sosté amb el hook commit-msg de la lliçó 06-01 per a la comoditat del desenvolupador i amb la validació al CI sobre branca protegida de la lliçó 07-06 per a allò innegociable, perquè --no-verify existeix.
• L'idioma es tria una vegada, s'escriu al README.md i no es discuteix més.

Queda un cap solt que l'exercici 3 ha deixat a la vista: un missatge excel·lent no serveix de res si la política d'integració l'esborra. I aquesta política —merge, squash o rebase— és exactament la decisió que vam deixar oberta a la lliçó 07-04 sobre GitHub Flow.

La resolem ara, juntament amb tota la resta que fa que un historial sigui llegible, bisecable i reversible, a la lliçó 08-02: Mantenint un Historial Net.