doc / configuration

Configurer un dépôt

La configuration d'un dépôt tient dans un seul fichier, .conventional-comments.json, placé sur la branche par défaut. Vous n'avez à y déclarer que ce que vous souhaitez modifier. Pour tout le reste, les valeurs par défaut du produit continuent de s'appliquer.

La configuration minimale

{
  "$schema": "https://conventionalcomments.io/schema/v1.json",
  "version": 1,
  "mode": "assist"
}

La propriété $schema n'est pas là pour faire joli. Votre éditeur l'utilise pour proposer l'autocomplétion des paramètres disponibles, afficher leur documentation au survol et signaler une valeur incorrecte comme "enforc" avant même le commit.

Trois niveaux de configuration

Le fichier du dépôt n'est qu'une des trois sources prises en compte. Elles sont combinées selon un ordre bien défini.

Niveau	Qui le définit	À quoi il sert
plancher	L'organisation, au moment du déploiement — jamais depuis un fichier de dépôt.	Impose un mode minimal et les règles qu'aucun dépôt ne peut désactiver. Un dépôt peut être plus strict, mais jamais plus permissif.
organisation	Un document de configuration partagé, récupéré depuis l'adresse définie par le plancher.	Définit la base commune. Modifier `mode` à ce niveau prend effet dans toute l'organisation, y compris sur les pull requests déjà ouvertes.
dépôt	Le fichier `.conventional-comments.json` de la branche par défaut.	Permet les ajustements locaux : exempter certains bots, activer un label optionnel ou désactiver un diagnostic.

qui applique le plancher aujourd'hui

Aujourd'hui, seule l'extension applique ce plancher, qu'elle lit dans la politique d'entreprise du navigateur. Un futur contrôle exécuté au niveau de la plateforme ne pourrait pas lire cette politique directement et devrait donc recevoir la même information par un autre mécanisme. Ce mécanisme n'est volontairement pas figé tant que l'implémentation d'Enforce n'a pas été définie pour chaque plateforme.

Les paramètres à connaître

La configuration en compte vingt-cinq au total. Ceux-ci sont les principaux paramètres qui modifient le comportement du produit plutôt que son apparence.

Clé	Valeur par défaut	Rôle
mode	assist	`off` · `assist` · `warn` · `enforce`. Assist et warn sont pleinement pris en charge par l'extension aujourd'hui. Enforce ajoute déjà un mode strict local dans le navigateur ; le contrôle de fusion au niveau de la plateforme reste, lui, sur la feuille de route. Consultez le guide d'adoption pour le détail.
formatSeverity	warn	Détermine si un commentaire mal formé peut faire échouer la vérification. La plupart des équipes conservent cette valeur : en règle générale, ce sont les points bloquants non résolus qui doivent empêcher une fusion, pas une erreur de format.
resolverOverrideGroup	vide	Définit qui peut passer outre une résolution et enregistrer une `decision`. Ce paramètre doit être configuré avant d'utiliser `enforce`. Lorsqu'il est vide, les deux mécanismes permettant de sortir d'une situation bloquée sont indisponibles.
exemptUsers	vide	Liste les utilisateurs dont les commentaires ne sont jamais validés. La comparaison se fait avec leur identifiant sur la plateforme, sans tenir compte de la casse.
toolCommands	vide	Définit les commentaires destinés à des bots ou à des outils. Voir le point d'attention ci-dessous.
labels	13 labels	Permet de modifier le comportement de certains labels. Ne déclarez que ceux que vous souhaitez personnaliser.
severities	valeurs du produit	Permet de modifier, diagnostic par diagnostic, leur niveau de sévérité ou de les désactiver.
coreMinVersion	1.0.0	Permet d'imposer une version minimale du moteur dans toute l'organisation.

un paramètre mérite une attention particulière

`toolCommands` est vide par défaut.

En mode strict, un /rebase utilisé seul est traité comme n'importe quel autre commentaire non conforme, sauf si le dépôt le déclare explicitement. Ajouter "/*" permet d'exempter toutes les commandes commençant par /. Les comptes de bots, eux, doivent être déclarés individuellement avec leur identifiant exact, par exemple "@dependabot".

Deux comportements à connaître

Une clé inconnue est ignorée et produit un avertissement ; elle ne rend pas la configuration invalide. En revanche, si une clé reconnue contient une valeur impossible, l'ensemble du document est considéré comme invalide. Puisqu'il ne peut plus être interprété de manière fiable, aucune de ses règles n'est appliquée.
Une propriété configUrl déclarée dans le fichier du dépôt est ignorée. L'adresse de la configuration de l'organisation provient exclusivement du plancher. Autoriser un dépôt à la redéfinir reviendrait à lui permettre de choisir lui-même les règles de l'organisation.