Contribuer au code

Vous envisagez de contribuer à Nette Framework et vous avez besoin de connaître les règles et les procédures ? Ce guide pour débutants vous accompagne pas à pas pour contribuer efficacement au code, travailler avec les dépôts et mettre en œuvre vos modifications.

Procédure

Pour contribuer au code, il est indispensable d'avoir un compte sur GitHub et de connaître les bases du système de gestion de versions Git. Si Git ne vous est pas familier, vous pouvez consulter git – the simple guide et envisager 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 comptez modifier
Clonez ce dépôt sur votre ordinateur
Installez les dépendances, Nette Tester compris, avec la commande composer install
Vérifiez que les tests fonctionnent en lançant composer tester
Créez une Nouvelle branche basée sur la dernière version publiée

Mise en œuvre de vos modifications

Vous pouvez maintenant apporter vos propres modifications au code :

Implémentez les changements souhaités et n'oubliez pas les tests
Assurez-vous que les tests passent avec composer tester
Vérifiez que le code respecte les Standards de codage
Enregistrez (commit) les changements avec une description dans ce format

Vous pouvez créer plusieurs commits, un par étape logique. Chaque commit doit avoir du sens à lui seul.

Soumission des modifications

Une fois satisfait de vos modifications, vous pouvez les soumettre :

Poussez les changements sur GitHub, dans votre fork
De là, soumettez-les au dépôt de Nette en créant une pull request (PR)
Donnez assez d'informations dans la description

Prise en compte des retours

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

Suivez les changements proposés
Intégrez-les sous forme 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, n'oubliez pas de l'ajouter aussi à la documentation.

Nouvelle branche

Si possible, faites vos modifications par rapport à la dernière version publiée, c'est-à-dire au dernier tag de la branche. Pour le tag v3.2.1, créez une branche avec cette commande :

git checkout -b new_branch_name v3.2.1

Standards de codage

Votre code doit respecter le standard de codage utilisé dans Nette Framework. Pour le vérifier et le corriger automatiquement, servez-vous de l'outil Nette Coding Standard, où vous trouverez aussi les instructions d'installation et d'utilisation.

Description du commit

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

Le domaine, suivi de deux-points
L'objet du commit au passé ; si possible, commencez par des mots comme : “added (nouvelle fonctionnalité)”, “fixed (correction)”, “refactored (changement de code sans changement de comportement)”, “changed”, “removed”
Si le commit casse la rétrocompatibilité, ajoutez “BC break”
Éventuellement un lien vers le gestionnaire de tickets, par ex. (#123) ou [Closes #69]
Après le sujet peut venir une ligne vide, suivie d'une description plus détaillée comprenant par exemple des liens vers le forum

Description de la pull request

À la création d'une pull request, l'interface de GitHub vous permet de saisir un titre et une description. Donnez un titre concis et mettez dans la description le maximum d'informations sur les raisons de votre changement.

Précisez aussi dans l'en-tête s'il s'agit d'une nouvelle fonctionnalité ou d'une correction de bug, et si cela peut poser des problèmes de rétrocompatibilité (BC break). S'il existe un ticket lié, faites-y référence pour qu'il se ferme à l'acceptation 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 -->