Contribuer au code TensorFlow

Que vous ajoutiez une fonction de perte, amélioriez la couverture des tests ou rédigiez une RFC pour un changement de conception majeur, cette partie 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 dans le dépôt GitHub du projet. Par exemple, consultez le fichier CONTRIBUTING.md dans le référentiel TensorFlow principal. Tous les contributeurs de code doivent signer un contrat de licence de contributeur (CLA).

Pour éviter la duplication du travail, veuillez consulter les RFC actuelles ou proposées et contacter les développeurs sur les forums TensorFlow ( développeurs@tensorflow.org ) avant de commencer à travailler sur une fonctionnalité non triviale. Nous sommes quelque peu sélectifs lorsque nous décidons d'ajouter de nouvelles fonctionnalités, et la meilleure façon de contribuer et d'aider le projet est de travailler sur des problèmes connus.

Problèmes pour les nouveaux contributeurs

Les nouveaux contributeurs doivent rechercher les balises suivantes lors de la recherche d'une première contribution à la base de code TensorFlow. Nous recommandons fortement aux nouveaux contributeurs de s'attaquer d'abord aux projets « bon premier numéro » et « contributions bienvenues » ; cela aide le contributeur à se familiariser avec le flux de travail de contribution et les principaux développeurs à se familiariser avec le contributeur.

Si vous souhaitez recruter une équipe pour vous aider à résoudre un problème à grande échelle ou une nouvelle fonctionnalité, veuillez envoyer un e-mail au groupe développeurs@ et consulter notre liste actuelle de RFC.

Révision des codes

Les nouvelles fonctionnalités, corrections de bogues et toute autre modification apportée à la base de code sont soumises à une révision du code.

L'examen du code contribué au projet sous forme de demandes d'extraction est un élément crucial du développement de TensorFlow. Nous encourageons quiconque à commencer à examiner le code soumis par d'autres développeurs, surtout si la fonctionnalité est quelque chose que vous êtes susceptible d'utiliser.

Voici quelques questions à garder à l’esprit lors du processus de révision du code :

  • Voulons-nous cela dans TensorFlow ? Est-il susceptible d'être utilisé ? En tant qu'utilisateur de TensorFlow, aimez-vous le changement et avez-vous l'intention de l'utiliser ? Ce changement concerne-t-il la portée de TensorFlow ? Le coût de maintenance d’une nouvelle fonctionnalité vaudra-t-il ses avantages ?
  • Le code est-il cohérent avec l'API TensorFlow ? Les fonctions, classes et paramètres publics sont-ils bien nommés et conçus de manière intuitive ?

  • Est-ce que cela inclut de la documentation ? Toutes les fonctions, classes, paramètres, types de retour et attributs stockés publics sont-ils nommés conformément aux conventions TensorFlow et clairement documentés ? Les nouvelles fonctionnalités sont-elles décrites dans la documentation de TensorFlow et illustrées par des exemples, dans la mesure du possible ? La documentation s'affiche-t-elle correctement ?

  • Le code est-il lisible par l'homme ? La redondance est-elle faible ? Les noms de variables devraient-ils être améliorés pour plus de clarté ou de cohérence ? Faut-il ajouter des commentaires ? Les commentaires devraient-ils être supprimés comme inutiles ou superflus ?

  • Le code est-il efficace ? Pourrait-il être réécrit facilement 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 sur d’autres bibliothèques ?

Tester et améliorer la couverture des tests

Des tests unitaires de haute qualité sont la pierre angulaire du processus de développement de TensorFlow. Pour cela, nous utilisons des images Docker. Les fonctions de test portent bien leur nom et sont chargées de vérifier la validité des algorithmes ainsi que des différentes options du code.

Toutes les nouvelles fonctionnalités et corrections de bogues doivent inclure une couverture de test adéquate. Nous apprécions également les contributions de nouveaux cas de test ou d’améliorations des tests existants. Si vous découvrez que nos tests existants ne sont pas terminés – même si cela ne provoque pas de bug actuellement – ​​veuillez signaler un problème et, si possible, une pull request.

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

Des préoccupations particulières en matière de tests adéquats :

  • Chaque fonction et classe publique est-elle testée ?
  • Un ensemble raisonnable de paramètres , leurs valeurs, types de valeurs et combinaisons sont-ils testés ?
  • Les tests valident-ils que le code est correct et qu'il fait ce que la documentation indique que le code est censé faire ?
  • Si le changement est une correction de bug, un test de non-régression est-il inclus ?
  • Les tests réussissent-ils la construction d’intégration continue ?
  • Les tests couvrent-ils chaque ligne de code ? Dans la négative, les exceptions sont-elles raisonnables et explicites ?

Si vous rencontrez des problèmes, pensez à aider le contributeur à comprendre ces problèmes et à les résoudre.

Améliorer les messages d'erreur ou les journaux

Nous apprécions les contributions qui améliorent les messages d’erreur et la journalisation.

Flux de travail des contributions

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

  1. Forkez le dépôt sur lequel vous prévoyez de travailler. Accédez à 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 façon de créer un référentiel, 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 contenir 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 vers votre dépôt GitHub.

    $ git push origin branch-name

  7. Ouvrez une Pull Request (PR). Accédez au dépôt du projet d'origine sur GitHub. Il y aura un message concernant votre branche récemment poussée, vous demandant si vous souhaitez ouvrir une pull request. Suivez les instructions, comparez les référentiels et soumettez le PR. Cela enverra un e-mail aux committers. Vous voudrez peut-être envisager d'envoyer un e-mail à la liste de diffusion pour plus de visibilité. (Pour plus de détails, consultez le guide GitHub sur les PR .

  8. Les responsables et autres contributeurs examineront votre PR . Veuillez participer à la conversation et essayer d' apporter les modifications demandées . Une fois le PR approuvé, le code sera fusionné.

Avant de travailler sur votre prochaine contribution , assurez-vous que votre référentiel local est à jour.

  1. Réglez la télécommande en amont. (Vous ne devez le faire qu'une fois par projet, pas à chaque fois.)

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

  2. Basculez vers la branche principale locale.

    $ git checkout master

  3. Déroulez les modifications depuis l’amont.

    $ git pull upstream master

  4. Envoyez les modifications à votre compte GitHub. (Facultatif, mais c'est une bonne pratique.)

    $ git push origin master

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

    $ git checkout -b branch-name

Ressources git et GitHub supplémentaires :

Liste de contrôle des contributeurs