Proposition de modification du code

Nette Framework utilise Git et GitHub pour maintenir la base de code. La meilleure façon de contribuer est de commettre vos changements dans votre propre fork et ensuite de faire une demande de pull sur GitHub. Ce document résume les principales étapes d'une contribution réussie.

Préparation de l'environnement

Commencez par forker Nette sur GitHub. Configurez soigneusement votre environnement Git local, configurez votre nom d'utilisateur et votre adresse e-mail, ces identifiants permettront d'identifier vos modifications dans l'historique du Framework Nette.

Travailler sur votre correctif

Avant de commencer à travailler sur votre patch, créez une nouvelle branche pour vos modifications.

git checkout -b new_branch_name

Vous pouvez travailler sur votre changement de code.

Si possible, effectuez les changements à partir de la dernière version publiée.

Test de vos modifications

Vous devez installer Nette Tester. Le moyen le plus simple est d'appeler composer install à la racine du référentiel. Maintenant vous devriez être capable d'exécuter des tests avec ./vendor/bin/tester dans le terminal.

Certains tests peuvent échouer à cause d'un php.ini manquant. Par conséquent, vous devez appeler le runner avec le paramètre -c et spécifier le chemin vers le php.ini, par exemple ./vendor/bin/tester -c ./tests/php.ini.

Une fois que vous êtes en mesure d'exécuter les tests, vous pouvez implémenter les vôtres ou modifier l'échec pour correspondre au nouveau comportement. Pour en savoir plus sur les tests avec Nette Tester, consultez la page de documentation.

Normes de codage

Votre code doit respecter les normes de codage utilisées dans Nette Framework. C'est facile car il existe un vérificateur et un fixateur automatiques. Il peut être installé via Composer dans le répertoire global de votre choix :

composer create-project nette/coding-standard /path/to/nette-coding-standard

Maintenant vous devriez être capable d'exécuter l'outil dans le terminal. Par exemple, cette commande vérifie et corrige le code dans les dossiers src et tests dans le répertoire actuel :

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Validation des modifications

Après avoir modifié le code, vous devez valider vos modifications. Créez plusieurs commits, un pour chaque étape logique. Chaque commit doit être utilisable tel quel – sans autres commits. Ainsi, les tests appropriés doivent également être inclus dans le même commit.

S'il vous plaît, vérifiez que votre code respecte les règles :

• Le code ne génère pas d'erreurs
• Votre code ne casse aucun test.
• Votre changement de code est testé.
• Vous ne commettez pas de modifications inutiles en espace blanc.

Le message de validation doit suivre le format suivant Latte: fixed multi template rendering [Closes # 69] c'est-à-dire

• une zone suivie de deux points
• le but du commit dans le passé, si possible, commencez par “ajouté.”, “corrigé.”, “refactorisé.”, changé, supprimé
• lien éventuel vers le suivi des problèmes
• si le commit annule la rétrocompatibilité, ajoutez “BC break”.
• il peut y avoir une ligne libre après le sujet et une description plus détaillée incluant des liens vers le forum.

Pull-Requesting des commits

Si vous êtes satisfait de vos modifications de code et de vos commits, vous devez pousser vos commits vers GitHub.

git push origin new_branch_name

Les changements sont présents publiquement, cependant, vous devez proposer vos changements pour l'intégration dans la branche master de Nette. Pour ce faire, faites une demande de modification (pull request). Chaque pull request a un titre et une description. Veuillez fournir un titre descriptif. Il est souvent similaire au nom de la branche, par exemple “Securing signals against CSRF attack”.

La description de la demande de téléchargement doit contenir des informations plus spécifiques sur les modifications apportées au code :

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

Veuillez modifier le tableau d'information pour l'adapter à votre demande de retrait. Commentaires pour chaque élément de la liste :

• Indique si la demande ajoute une fonctionnalité ou s'il s'agit d'un bugfix.
• Fait éventuellement référence à un problème connexe, qui sera fermé après la fusion de la demande.
• Indique si la demande nécessite des modifications de la documentation, si oui, fournit des références aux demandes pull appropriées. Vous n'êtes pas obligé de fournir la modification de la documentation immédiatement, cependant, la demande pull ne sera pas fusionnée si la modification de la documentation est nécessaire. Le changement de documentation doit être préparé pour la documentation en anglais, les mutations dans d'autres langues sont facultatives.
• Indique si la pull request crée une rupture de la BC. S'il vous plaît, considérez tout ce qui change l'interface publique comme une rupture de la CB.

Le tableau final pourrait ressembler à ceci :

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Retravailler vos modifications

Il est très courant de recevoir des commentaires sur vos modifications de code. Essayez de suivre les changements proposés et retravaillez vos commits pour y parvenir. Vous pouvez commiter les changements proposés en tant que nouveaux commits et ensuite les écraser sur les commits précédents. Voir le chapitre sur le rebasement interactif sur GitHub. Après avoir rebasé vos modifications, forcez vos modifications à votre fork distant, tout sera automatiquement propagé à la pull request.