Contribuer au code

Vous envisagez de contribuer au Nette Framework et avez besoin de vous familiariser avec les règles et les procédures ? Ce guide du débutant vous guidera à travers les étapes pour contribuer efficacement au code, travailler avec les dépôts et mettre en œuvre les changements.

Procédure

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

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

  1. Sur GitHub, créez un fork du dépôt de paquets que vous avez l'intention de modifier.
  2. Clonez ce dépôt sur votre ordinateur
  3. Installez les dépendances, y compris Nette Tester, en utilisant la commande composer install
  4. Vérifiez que les tests fonctionnent en exécutant la commande composer tester
  5. Créer une nouvelle branche basée sur la dernière version publiée.

Mise en œuvre de vos propres modifications

Vous pouvez maintenant apporter vos propres modifications au code :

  1. Mettez en œuvre les changements souhaités et n'oubliez pas les tests.
  2. Assurez-vous que les tests s'exécutent avec succès en utilisant composer tester
  3. Vérifier si le code répond aux normes de codage
  4. Sauvegarder (commit) les changements avec une description dans ce format

Vous pouvez créer plusieurs livraisons, une pour chaque étape logique. Chaque validation doit être significative en soi.

Soumettre des modifications

Une fois que vous êtes satisfait des modifications, vous pouvez les soumettre :

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

Incorporer le retour d'information

Vos modifications sont maintenant visibles par les autres. Il est courant de recevoir des commentaires contenant des suggestions :

  1. Garder une trace des changements proposés
  2. Incorporez-les en tant que nouveaux commits ou fusionnez-les avec les précédents
  3. Resoumettez les commits à GitHub, et ils apparaîtront automatiquement dans la demande d'extraction.

Ne créez jamais une nouvelle demande d'extraction pour modifier une demande existante.

Documentation

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

Nouvelle branche

Si possible, effectuez les modifications par rapport à la dernière version publiée, c'est-à-dire la dernière balise de la branche. Pour l'étiquette v3.2.1, créez une branche en utilisant cette commande :

git checkout -b new_branch_name v3.2.1

Normes de codage

Votre code doit respecter les normes de codage utilisées dans le Nette Framework. Il existe un outil automatique pour vérifier et corriger le code. Vous pouvez l'installer globalement via Composer dans un dossier de votre choix :

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

Vous devriez maintenant être en mesure de lancer l'outil dans le terminal. La première commande vérifie et la seconde corrige le code dans les dossiers src et tests dans le répertoire courant :

/path/to/nette-coding-standard/ecs check
/path/to/nette-coding-standard/ecs check --fix

Description de l'engagement

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

  • domaine suivi de deux points
  • l'objet du commit au passé ; si possible, commencer par des mots comme : added, fixed, refactored, changed, removed
  • si le commit rompt la compatibilité ascendante, ajouter “BC break” (rupture de la compatibilité ascendante)
  • toute connexion à l'outil de suivi des problèmes, comme (#123) ou [Closes #69]
  • après le sujet, il peut y avoir une ligne vide suivie d'une description plus détaillée, y compris, par exemple, des liens vers le forum.

Description de la demande de retrait

Lors de la création d'une demande d'extraction, l'interface GitHub vous permet de saisir un titre et une description. Fournissez un titre concis et incluez autant d'informations que possible dans la description sur les raisons de votre changement.

Précisez également dans l'en-tête s'il s'agit d'une nouvelle fonctionnalité ou d'une correction de bogue et si elle peut entraîner des problèmes de compatibilité ascendante (BC break). S'il existe un problème connexe, créez un lien vers celui-ci afin qu'il soit fermé lors de l'approbation de la demande d'extraction.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->
  1. Documentation
  2. Devenez un contributeur de Nette
  3. Contribuer au code