Gerrit/Commit message guidelines/fr

Le message de validation de vos modifications joue un rôle important. C'est la première chose que les autres personnes verront concernant vos modifications.

Sujet
La première ligne du message de validation est connue comme le sujet. Le sujet doit avoir une longueur inférieure à 80 caractères (en général 50-70).


 * Résumez vos modifications sur la ligne du sujet. Notez bien que cela restera dans le dépôt pour toujours.
 * Utilisez le ton impératif pour la ligne du sujet. Le ton impératif est celui que vous utiliseriez pour donner des instructions à quelqu'un. Il commence par des mots comme « Changer », « Ajouter », « Supprimer », « Mettre à jour », « Refactoriser » ou « Documenter » par exemple. Des exemples corrects sont « Add Badge::query pour interroger l'API » ou « Permettre des zéros dans SimpleBadge::add ». De mauvais exemples seraient l'utilisation du participe passé comme dans « la méthode Added Badge::query »  ou « méthode Fixed Badge::query », ou des formes actives telles que « Badge peut appeler l'API »  et « Les zéros sont autorisés pour ajouter des badges ».
 * Ne terminez pas la ligne du sujet par une virgule (point).
 * Eventuellement, préfixez le sujet avec le composant auquel il se rapporte. Un composant représente le domaine général qui sera modifié par votre validation.

Corps
Lorsque vous rédigez votre texte, posez-vous les questions suivantes :


 * Pourquoi cette modification devrait être faite ? Qu'est-ce qui ne va pas avec le code actuel ?
 * Pourquoi de cette manière ? Y a-t-il d'autres moyens ?
 * Avez-vous envisagé d'autres solutions ? Si c'est le cas, expliquez pourquoi elles n'étaient pas aussi concluantes.
 * Comment un relecteur peut-il tester ou vérifier que votre code fonctionne correctement ?

A faire :

If necessary, refer to not-yet-merged commits by using a Gerrit Change-Id.
 * Séparez le corps du sujet en intercalant une ligne vide.
 * Structurez le corps du message de manière à ce que les lignes contiennent moins de 100 caractères. Mais il ne faut pas couper ni replier les URLs, gardez les telles quelles même si elles sont très longues.
 * Format "Bug" and "Change-Id" meta-data exactly like in the examples below, and place them together at the end of the body, after one empty line.
 * Refer to other (merged) commits by using a (short) Git commit hash.

Ne faites pas :

This allows easy navigation of the Git repository when offline. It also allows users of all repository viewers (Gerrit, Gitiles, Phabricator, GitHub, and local Git interfaces) to automatically navigate to other commits within the same interface. A URL can only be resolved when online and using Gerrit, which breaks the ability for people to navigate quickly. If the change is justified by discussions elsewhere or external documentation, then briefly summarise the relevant points in the commit message.
 * Do not refer to other commits with a Gerrit URL, instead use the Git commit hash.
 * Do not use a URL as the only explanation for a change.

Bon exemple
jquery.badge: Add ability to display the number zero

Cupcake ipsum dolor sit. Amet tart cheesecake tiramisu chocolate cake topping. Icing ice cream sweet roll. Biscuit dragée toffee wypas.

Does not yet address T44834 or T176. Follow-up to Id5e7cbb1.

Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Mauvais exemple
Improved the code by fixing a bug.

Changed the files a.php and b.php

Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Sujet
Most programs we use that display Git commit, render the subject line as plain text. This means URLs do not work, and selecting/copying of text often is not possible. Therefore, do not mention Phabricator tasks, Git commits, or urls inside the subject line. Instead, mention those in the body text, or footer meta-data. That way, they can be universally selected, copied, or clicked.

,,  ,  , etc.
 * Gerrit uses the subject in: email notifications, IRC notifications, search results.
 * GitHub uses the subject in: commit history, commit subject.
 * The Git CLI uses the subject in:
 * et plus encore !
 * et plus encore !

Composant
You may start the subject line with a component, which will indicate what area of the project is changed by your commit.

It should be one of the following:


 * A directory of PHP classes under  or , such as "installer", "jobqueue", "objectcache", "resourceloader", "rdbms", etc.
 * A PHP class name, such as "Title", "User", "OutputPage", etc.; typically for classes without subdirectory in.
 * ResourceLoader module name (like "mediawiki.Title", "mediawiki.util", etc.).
 * Generic keyword affecting multiple areas relating to the type of change, such as:
 * "build" - for changes to files relating to the development workflow, such as updates to,  , etc.
 * "tests", "qunit", "phpunit" - for changes that only affect unit or integration test suites, or the test suite runners.

Phabricator
To reference a bug or task, in the commit message mention it inline using the Txxx notation (e.g. " That was caused by T169. ")

To express that a commit resolves (even partially) or is specially relevant to a bug, add  in the footer at the end of the commit message. (If you're amending a commit message, insert it immediately above the  line, without an empty line between them.)

Bug: T169

A bot will automatically leave a comment on the Phabricator task about any significant events (being merged, abandoned, etc.). If a patch resolves two or more bugs, put each  reference on its own line at the bottom.

Cross-références
Whenever you refer to another commit, use the SHA-1 git hash of the merged commit. If the commit in still pending review, use the Gerrit Change-Id hash instead of the git hash because the hash relates to an individual patch set (which changes when rebased, thus creating a dead-end).

Change-Id
's  tool will automatically append the "Change-Id: Ixxx" keyword to new commits.

Dépendances
If you have cross-repo dependencies (your commit depends on another commit in a different repository), declare them by adding  to the last paragraph. ("Ixxx"... is the  of the other commit.) This will instruct Zuul to test the commit together with that one.

Créditer d'autres personnes
Add this line before the Change-id to credit other developers working on the change. You can add more than one separated by a line break.

Lectures complémentaires

 * Node.js Instructions pour le Commit
 * Git Core Commit Guidelines
 * jQuery Commit Guidelines
 * Erlang Commit Guidelines
 * Une note concernant les messages Git de validation (commit) - par Tim Pope
 * Comment écrire un message Git Commit - par Chris Beams
 * Gerrit integrations with the Puppet Catalogue Compiler
 * Comment écrire un message Git Commit - par Chris Beams
 * Gerrit integrations with the Puppet Catalogue Compiler