Comment contribuer au code

Vous êtes sur le point de contribuer à Nette Framework et avez besoin de vous familiariser avec les règles et procédures ? Ce guide pour débutants vous montrera étape par étape comment contribuer efficacement au code, travailler avec les dépôts et implémenter des changements.

Procédure

Pour contribuer au code, il est nécessaire d'avoir un compte sur GitHub et d'être familiarisé avec les bases du travail avec le système de contrôle de version Git. Si vous ne maîtrisez pas Git, vous pouvez consulter le guide git – le guide simple ou utiliser l'un des nombreux clients graphiques.

Préparation de l'environnement et du dépôt

Sur GitHub, créez un fork du dépôt du paquet que vous vous apprêtez à modifier.
Clonez ce dépôt sur votre ordinateur.
Installez les dépendances, y compris Nette Tester, à l'aide de la commande composer install.
Vérifiez que les tests fonctionnent en exécutant composer tester.
Créez une nouvelle branche basée sur la dernière version publiée.

Implémentation de vos propres changements

Vous pouvez maintenant effectuer vos propres modifications de code :

Programmez les changements souhaités et n'oubliez pas les tests.
Assurez-vous que les tests réussissent en utilisant composer tester.
Vérifiez que le code respecte le standard de codage.
Enregistrez (commitez) les changements avec une description dans ce format.

Vous pouvez créer plusieurs commits, un pour chaque étape logique. Chaque commit doit être autonome et avoir un sens.

Envoi des changements

Une fois que vous êtes satisfait des changements, vous pouvez les envoyer :

Envoyez (pushez) les changements sur GitHub vers votre fork.
De là, envoyez-les au dépôt Nette en créant une pull request (PR).
Fournissez suffisamment d'informations dans la description.

Intégration des commentaires

Vos commits seront désormais visibles par les autres. Il est courant de recevoir des commentaires avec des remarques :

Suivez les modifications suggérées.
Intégrez-les comme de nouveaux commits ou fusionnez-les avec les précédents.
Renvoyez les commits sur GitHub ; ils apparaîtront automatiquement dans la pull request.

Ne créez jamais une nouvelle pull request pour modifier une pull request existante.

Documentation

Si vous avez modifié une fonctionnalité ou en avez ajouté une nouvelle, n'oubliez pas de l'ajouter à la documentation.

Nouvelle branche

Si possible, effectuez les changements par rapport à la dernière version publiée, c'est-à-dire le dernier tag dans la branche concernée. Pour le tag v3.2.1, vous créez une branche avec cette commande :

git checkout -b nom_nouvelle_branche v3.2.1

Standards de codage

Votre code doit respecter le standard de codage utilisé dans Nette Framework. Un outil automatique est disponible pour vérifier et corriger le code. Il peut être installé via Composer globalement dans le dossier de votre choix :

composer create-project nette/coding-standard /chemin/vers/nette-coding-standard

Vous devriez maintenant pouvoir exécuter l'outil dans le terminal. La première commande vérifie et la seconde corrige également le code dans les dossiers src et tests du répertoire courant :

/chemin/vers/nette-coding-standard/ecs check
/chemin/vers/nette-coding-standard/ecs check --fix

Description du commit

Dans Nette, les sujets des commits ont le format : Presenter: fixed AJAX detection [Closes #69]

la zone suivie de deux-points
l'objectif du commit au passé, si possible, commencez par le mot : “added (nouvelle fonctionnalité ajoutée)”, “fixed (correction)”, “refactored (modification du code sans changement de comportement)”, changed, removed
si le commit rompt la compatibilité ascendante, ajoutez “BC break”
une éventuelle liaison avec le suivi des problèmes comme (#123) ou [Closes #69]
après le sujet, une ligne vide peut suivre, puis une description plus détaillée incluant par exemple des liens vers le forum

Description de la pull request

Lors de la création d'une pull request, l'interface GitHub vous permettra de saisir un titre et une description. Donnez un titre concis et dans la description, fournissez autant d'informations que possible sur les raisons de votre changement.

Un en-tête s'affichera également, où vous spécifierez s'il s'agit d'une nouvelle fonctionnalité ou d'une correction de bug et si cela peut entraîner une rupture de compatibilité ascendante (BC break). S'il existe un problème lié (issue), référencez-le afin qu'il soit fermé après l'approbation de la pull request.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->