Provenance des hotfixes

Une branche de hotfix est créée à partir de la release en production, et le correctif est repris depuis la branche par défaut. La provenance des hotfixes garantit que rien d’autre ne s’y passe. Sur une branche qui correspond à votre motif de hotfix (hotfix/* par défaut), chaque commit doit être :

un git cherry-pick -x d’un commit de la branche par défaut du dépôt ;
dont la pull request fusionnée porte votre étiquette de voie rapide (fast-track par défaut) ;
et dont la modification est identique à celle du commit source.

fremforge vérifie chaque commit d’une pull request vers une branche de hotfix, et chaque commit poussé sur l’une d’elles, et publie le résultat sous forme de statut de commit fremforge/hotfix-provenance : success, ou failure en nommant le premier commit qui ne passe pas et la raison. Vous pouvez en faire un contrôle obligatoire.

La provenance des hotfixes est désactivée par défaut. Un propriétaire de l’organisation l’active via l’API.

Réaliser un hotfix

# 1. Fix it on the default branch first, through a pull request with the label `fast-track`.
# 2. Cut the hotfix branch from the production tag and push it:
git switch -c hotfix/1.4.2 v1.4.1
git push -u origin hotfix/1.4.2
# 3. Carry the fix over on a branch of its own. -x writes the "(cherry picked from commit ...)" line:
git switch -c backport/login-fix
git cherry-pick -x <the commit the merge put on main>
git push -u origin backport/login-fix
# 4. Open a pull request from backport/login-fix into hotfix/1.4.2.

Faites le cherry-pick du commit que la fusion a placé sur la branche par défaut : le commit squash, ou le commit de fusion (git cherry-pick -x -m 1 <merge>). fremforge retrouve la pull request de la source à partir de ce commit. Avec les fusions par rebase, seul le dernier commit d’une pull request rebasée peut être retrouvé de cette façon.

Ce qui échoue, et pourquoi

Le statut nomme le premier commit qui échoue et le nombre des autres. Chaque commit est listé dans l’explication.

Problème	Ce que cela signifie
no “cherry picked from commit” line	Le commit n’a pas été créé avec `git cherry-pick -x`. Un identifiant de commit abrégé ne compte pas.
a merge commit	Les commits de fusion ne sont pas acceptés sur une branche de hotfix, y compris une fusion du tag de production. Créez la branche à partir du tag et faites les cherry-picks dessus.
source … is not on `main`	Le commit d’origine n’est pas sur la branche par défaut, par exemple parce qu’il est encore sur une branche de fonctionnalité.
source … is not a commit of this repository	L’identifiant indiqué dans la ligne n’existe pas dans ce dépôt.
source … was not merged by a pull request	La source a atteint la branche par défaut sans pull request.
source pull request #… lacks the label	Ajoutez l’étiquette à cette pull request. Elle compte même après la fusion (voir ci-dessous).
its change differs from source …	Le cherry-pick a modifié quelque chose que la source n’a pas modifié, par exemple un conflit résolu à la main.
names several source commits	Avec la comparaison des modifications activée, faites le cherry-pick d’un seul commit par commit.
more than 50 commits	Un hotfix contient au plus 50 commits.

Comment fremforge décide :

Quels commits comptent. Pour une pull request vers une branche de hotfix, ses propres commits. Pour un push sur une branche de hotfix, chaque commit de la branche qui n’est pas sur la branche par défaut. Le tag de production à partir duquel la branche a été créée est sur la branche par défaut, il ne compte donc jamais. Créez les branches de hotfix à partir d’un commit de la branche par défaut.
Les force-pushes sont vérifiés depuis le début : fremforge examine toute la branche, jamais uniquement les commits du dernier push.
La comparaison des modifications fonctionne comme git patch-id : elle compare les lignes que chaque commit ajoute et supprime, fichier par fichier, en ignorant les espaces, les numéros de ligne et les lignes environnantes. Un cherry-pick sur une release plus ancienne correspond donc à sa source. Vous pouvez la désactiver (diff_check: false).
Une étiquette ajoutée après la fusion compte. fremforge lit les étiquettes de la pull request source au moment de la vérification. Ajouter l’étiquette à une pull request fusionnée revérifie en quelques secondes les pull requests de hotfix ouvertes de ce dépôt.
Les commits des bots ne bénéficient d’aucune exemption. Le backport d’un bot est un cherry-pick comme un autre.
Après la fusion d’une pull request. Lors d’un push, le commit squash ou de fusion créé par une pull request fusionnée vers la même branche de hotfix est considéré comme vérifié, à condition que fremforge/hotfix-provenance ait réussi sur cette pull request.

Le statut ne réussit jamais par erreur

Si fremforge ne peut pas terminer la vérification, par exemple parce que le dépôt n’a pas pu être lu à temps (30 secondes), le statut est pending, en l’indiquant, et il est revérifié dans les 5 minutes. Il n’est jamais success pour un commit qui n’a pas pu être vérifié.

Sur une branche qui n’est pas une branche de hotfix, fremforge ne publie rien, sauf si la règle de cette branche exige fremforge/hotfix-provenance. Il publie alors success, « Not a hotfix branch », afin qu’aucune pull request ne l’attende. Il en va de même pour un dépôt où la provenance des hotfixes est désactivée : « not evaluated ».

fremforge publie le statut quelques secondes après qu’une pull request a été ouverte, a reçu un push, a été modifiée ou a changé de branche cible, et après un push sur une branche de hotfix. Une tâche lancée toutes les 5 minutes revérifie toute pull request de hotfix ouverte dont le statut est manquant, pending ou failure.

L’activer

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/hotfix-provenance/settings \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "on", "branch_pattern": "hotfix/*", "required_label": "fast-track"}'

Champ	Remarques
`mode`	`off` ou `on`. Obligatoire.
`branch_pattern`	Les branches qui sont des branches de hotfix. `` correspond à l’intérieur d’un seul niveau, `` à travers les niveaux : `hotfix/`, `release/**`. Un motif qui correspond à toutes les branches est refusé. Inchangé s’il est omis.
`required_label`	L’étiquette que doit porter la pull request source. Comparée sans tenir compte de la casse. Inchangé s’il est omis.
`diff_check`	`true` (par défaut) pour exiger que la modification de chaque cherry-pick soit identique à celle de sa source. Inchangé s’il est omis.
`repos`	Paramètres par dépôt, qui remplacent la liste actuelle : `[{"repo": "api", "enabled": true, "branch_pattern": "release/**", "required_label": "backport"}]`. `enabled` active un dépôt pendant que l’organisation est désactivée, pour l’essayer, ou le désactive pendant qu’elle est activée. Inchangé s’il est omis.

Le jeton doit avoir policy:write ; GET sur le même chemin nécessite policy:read. Chaque modification est auditée sous hotfix_provenance.settings_updated.

En faire un contrôle obligatoire

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/hotfix-provenance/enforcement \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "*"}'

repo est un nom de dépôt, ou * pour tous les dépôts, y compris ceux créés plus tard. fremforge publie d’abord le statut sur chaque pull request ouverte vers une branche de hotfix, et ce n’est qu’ensuite qu’il ajoute fremforge/hotfix-provenance à la règle de branche qui porte le nom du motif (par exemple une règle nommée hotfix/*), en conservant les autres contrôles de la règle. Une fusion depuis la page web, l’API ou la file de fusion l’attend alors.

fremforge ne crée jamais de règle de branche. Un dépôt sans règle pour le motif est listé dans unprotected ; créez la règle (Paramètres → Branches), et la tâche ajoute le contrôle dans les 5 minutes. DELETE sur le même chemin avec le même corps le retire. Le jeton doit avoir policy:write. Les deux sont audités, sous hotfix_provenance.enforcement_enabled et hotfix_provenance.enforcement_disabled.

Pourquoi une pull request réussit ou échoue

curl https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/pulls/<number>/hotfix-provenance \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

La réponse liste chaque commit avec le fait qu’il a réussi ou non, le commit source que nomme sa ligne, la pull request de la source et, pour un commit en échec, le problem et la raison en clair. Cela fonctionne aussi lorsque la provenance des hotfixes est désactivée, ce qui vous permet de l’essayer d’abord sur une vraie pull request. Le jeton doit avoir findings:read, ou un accès en lecture au dépôt.