Contribuer au code TensorFlow

Que vous ajoutiez une fonction de perte, amélioriez la couverture des tests ou rédigiez une RFC pour une modification majeure de la conception, cette section du guide du contributeur vous aidera à démarrer. Merci pour votre travail et votre intérêt pour l'amélioration de TensorFlow.

Avant de commencer

Avant de contribuer au code source d'un projet TensorFlow, veuillez consulter le fichier CONTRIBUTING.md du dépôt GitHub du projet. Par exemple, consultez le fichier CONTRIBUTING.md du dépôt TensorFlow principal. Tous les contributeurs de code sont tenus de signer un contrat de licence de contributeur (CLA).

Pour éviter les doublons, veuillez consulter les RFC existantes ou proposées et contacter les développeurs sur les forums TensorFlow ( developers@tensorflow.org ) avant de commencer à travailler sur une fonctionnalité complexe. Nous sommes assez sélectifs quant à l'ajout de nouvelles fonctionnalités, et la meilleure façon de contribuer au projet est de travailler sur les problèmes connus.

Problèmes rencontrés par les nouveaux contributeurs

Les nouveaux contributeurs sont invités à rechercher les étiquettes suivantes lorsqu'ils souhaitent contribuer pour la première fois au code source de TensorFlow. Nous leur recommandons vivement de commencer par les projets « good first issue » et « contribution welcome » ; cela leur permettra de se familiariser avec le processus de contribution et aux développeurs principaux de faire leur connaissance.

Si vous souhaitez recruter une équipe pour vous aider à résoudre un problème d'envergure ou à développer une nouvelle fonctionnalité, veuillez envoyer un e-mail à developers@group et consulter notre liste actuelle de RFC.

revue de code

Les nouvelles fonctionnalités, les corrections de bugs et toute autre modification du code source sont soumises à une revue de code.

L'examen du code soumis au projet via les demandes de fusion est une étape cruciale du développement de TensorFlow. Nous encourageons tous les développeurs à examiner le code proposé, surtout si la fonctionnalité en question vous sera utile.

Voici quelques questions à garder à l'esprit lors du processus de revue de code :

  • Souhaitons-nous intégrer cette fonctionnalité à TensorFlow ? Est-elle susceptible d'être utilisée ? En tant qu'utilisateur de TensorFlow, appréciez-vous cette modification et comptez-vous l'utiliser ? Cette modification s'inscrit-elle dans le cadre de TensorFlow ? Les coûts de maintenance de cette nouvelle fonctionnalité seront-ils justifiés par ses avantages ?
  • Le code est-il conforme à l'API TensorFlow ? Les fonctions publiques, les classes et les paramètres sont-ils bien nommés et conçus de manière intuitive ?

  • La documentation est-elle incluse ? Les fonctions publiques, les classes, les paramètres, les types de retour et les attributs stockés sont-ils tous nommés conformément aux conventions TensorFlow et clairement documentés ? Les nouvelles fonctionnalités sont-elles décrites dans la documentation TensorFlow et illustrées par des exemples, lorsque cela est possible ? La documentation s'affiche-t-elle correctement ?

  • Le code est-il lisible ? Est-il peu redondant ? Les noms des variables devraient-ils être améliorés pour plus de clarté ou de cohérence ? Faut-il ajouter des commentaires ? Faut-il supprimer les commentaires inutiles ou superflus ?

  • Le code est-il efficace ? Pourrait-il être facilement réécrit pour fonctionner plus efficacement ?

  • Le code est -il rétrocompatible avec les versions précédentes de TensorFlow ?

  • Le nouveau code ajoutera-t-il de nouvelles dépendances à d'autres bibliothèques ?

Tester et améliorer la couverture des tests

Les tests unitaires de haute qualité constituent un pilier du processus de développement de TensorFlow. À cette fin, nous utilisons des images Docker. Les fonctions de test sont nommées de manière explicite et permettent de vérifier la validité des algorithmes ainsi que les différentes options du code.

Toute nouvelle fonctionnalité et correction de bug doit être accompagnée de tests complets. Nous acceptons également les contributions de nouveaux cas de test ou d'améliorations des tests existants. Si vous constatez que nos tests actuels sont incomplets (même si cela ne provoque pas de bug actuellement), veuillez ouvrir un ticket et, si possible, une pull request.

Pour plus de détails sur les procédures de test de chaque projet TensorFlow, consultez les fichiers README.md et CONTRIBUTING.md du dépôt du projet sur GitHub.

Parmi les préoccupations particulières concernant les tests adéquats :

  • Chaque fonction et classe publique est-elle testée ?
  • Un ensemble raisonnable de paramètres , leurs valeurs, leurs types de valeurs et leurs combinaisons sont-ils testés ?
  • Les tests permettent-ils de vérifier que le code est correct et qu'il fait bien ce que la documentation indique ?
  • Si la modification consiste à corriger un bug, un test de non-régression est-il inclus ?
  • Les tests réussissent-ils la compilation d'intégration continue ?
  • Les tests couvrent-ils chaque ligne de code ? Sinon, les exceptions sont-elles raisonnables et explicites ?

Si vous rencontrez des problèmes, merci d'aider le contributeur à les comprendre et à les résoudre.

Améliorer les messages d'erreur ou les journaux

Nous accueillons favorablement les contributions qui améliorent les messages d'erreur et la journalisation.

Flux de travail de contribution

Les contributions au code (corrections de bogues, nouveaux développements, améliorations des tests) suivent un flux de travail centré sur GitHub. Pour participer au développement de TensorFlow, créez un compte GitHub. Ensuite :

  1. Créez une copie du dépôt sur lequel vous souhaitez travailler. Rendez-vous sur la page du dépôt du projet et utilisez le bouton « Fork » . Cela créera une copie du dépôt sous votre nom d'utilisateur. (Pour plus de détails sur la procédure de fork d'un dépôt, consultez ce guide .)

  2. Clonez le dépôt sur votre système local.

    $ git clone git@github.com:your-user-name/project-name.git

  3. Créez une nouvelle branche pour y stocker votre travail.

    $ git checkout -b new-branch-name

  4. Travaillez sur votre nouveau code. Écrivez et exécutez des tests.

  5. Validez vos modifications.

    $ git add -A

    $ git commit -m "commit message here"

  6. Envoyez vos modifications à votre dépôt GitHub.

    $ git push origin branch-name

  7. Ouvrez une demande de fusion (PR). Rendez-vous sur le dépôt GitHub du projet d'origine. Un message concernant votre branche récemment poussée vous demandera si vous souhaitez ouvrir une demande de fusion. Suivez les instructions, comparez les dépôts et soumettez la PR. Un e-mail sera alors envoyé aux contributeurs. Vous pouvez également envisager d'envoyer un e-mail à la liste de diffusion pour une meilleure visibilité. (Pour plus de détails, consultez le guide GitHub sur les demandes de fusion .)

  8. Les responsables et autres contributeurs examineront votre demande de fusion . Veuillez participer à la discussion et tenter d' apporter les modifications demandées . Une fois la demande de fusion approuvée, le code sera intégré.

Avant de travailler sur votre prochaine contribution , assurez-vous que votre dépôt local est à jour.

  1. Configurez le dépôt distant en amont. (Vous n'aurez à le faire qu'une seule fois par projet, et non à chaque fois.)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. Basculez vers la branche master locale.

    $ git checkout master

  3. Récupérez les modifications depuis la source.

    $ git pull upstream master

  4. Transférez les modifications sur votre compte GitHub. (Facultatif, mais recommandé.)

    $ git push origin master

  5. Créez une nouvelle branche si vous commencez un nouveau travail.

    $ git checkout -b branch-name

Ressources supplémentaires concernant git et GitHub :

Liste de vérification des contributeurs