c590.md

Convention c590

Il s'agit d'une convention d'écriture de validation Git visant un résultat simple, lisible par l'utilisation de glyphes conventionnels et courts.

Exemples

main: [-] opt. -t, type de données, [+] arg pos.

L'option -t est abandonné en faveur d'un argument positionnel.

chiffre: [f] généricité des chiffres crypto.

Cette fonctionnalité très complexe fournit les différents avantages:

* Fonction générique de chiffrement de données `.encrypt()`.
* Ajout facile d'un chiffre.
* Meilleur pistage des erreurs de régression.

Description d'une validation

Une description doit être écrite de façon à expliquer pleinement ce sur quoi porte les changements. Ci-après les différentes conventions relativement

Format

Le format d'une description est prescrit par le bloc de texte brute suivant:

sujet: [code] description courte sur une ligne

Description longue plus approfondie et portant sur la liste des
changements apportés. Il s'agit d'un

ou plusieurs paragraphes respectant une longueur déterminé.
Accessoirement, des listes à puces peuvent être utilisés

* si cela permet une meilleure lisibilité;
* dans le cas où plusieurs éléments distincts interviennent.

La description termine possiblement par une ligne indiquant un ticket
fermé par la validation.

Ferme: #8358, #8344

• Longueur de la première ligne: <=50 caractères.
• Longueur des paragraphes: <=72 caractères.

Formatage de la première ligne

sujet: [code] description

• Le code est un caractère (voir la section Codification des modifications) dénotant la nature de la validation (ajout, correction, suppression, ...).
• Le sujet est la description de ce qui borne les changements, c.-à-d. à quoi est rattaché le changement effectué. Ce mot est souvent le nom du fichier contenant la modification.
• La description permet de saisir pleinement la contenu de la validation. La rédiger le moins vague possible. S'il y a un besoin d'espace abréger des mots ou omettre des déterminants p. ex.

Codification des modifications

• /: correction de contenu/fonctionnalité anciennement présente. Cela doit nécessairement corriger un défaut (possiblement rattaché à un ticket).
• +: Ajout de contenu.
• f: Comme +, mais consiste en une fonctionnalité nouvelle en soi. Cela est donc réservé pour des validations portant sur du code qui produit un nouveau comportement impossible avant son apparition.
• -: Retrait de contenu.
• d: Documentation du projet.
• t: Changements portant sur des tests pour le programme développé.

Auteur

Simon Désaulniers (sim.desaulniers@gmail.com). Remerciments distingués à Gabrielle Harrison-Hunter pour l'inspiration.