Contribuisci al codice TensorFlow

Che tu stia aggiungendo una funzione di perdita, migliorando la copertura del test o scrivendo una RFC per una modifica di progettazione importante, questa parte della guida per il collaboratore ti aiuterà a iniziare. Grazie per il tuo lavoro e il tuo interesse nel migliorare TensorFlow.

Prima di iniziare

Prima di contribuire con il codice sorgente a un progetto TensorFlow, esamina il file CONTRIBUTING.md nel repository GitHub del progetto. Ad esempio, consulta il file CONTRIBUTING.md nel repository TensorFlow principale. Tutti i contributori del codice sono tenuti a firmare un contratto di licenza per contributori (CLA).

Per evitare duplicazioni del lavoro, esamina le RFC attuali o proposte e contatta gli sviluppatori sui forum di TensorFlow ( developers@tensorflow.org ) prima di iniziare a lavorare su una funzionalità non banale. Siamo piuttosto selettivi quando decidiamo di aggiungere nuove funzionalità e il modo migliore per contribuire e aiutare il progetto è lavorare su problemi noti.

Problemi per i nuovi contributori

I nuovi contributori dovrebbero cercare i seguenti tag quando cercano un primo contributo alla base di codice TensorFlow. Raccomandiamo vivamente che i nuovi contributori affrontino prima i progetti "buono primo numero" e "contributi graditi"; questo aiuta il collaboratore a familiarizzare con il flusso di lavoro del contributo e gli sviluppatori principali a conoscere il collaboratore.

Se sei interessato a reclutare un team per aiutarti ad affrontare un problema su larga scala o una nuova funzionalità, invia un'e-mail al gruppo sviluppatori@ e consulta il nostro elenco attuale di RFC.

Revisione del codice

Nuove funzionalità, correzioni di bug e qualsiasi altra modifica al codice base sono soggetti a revisione del codice.

La revisione del codice contribuito al progetto come richieste pull è una componente cruciale dello sviluppo di TensorFlow. Incoraggiamo chiunque a iniziare a rivedere il codice inviato da altri sviluppatori, soprattutto se la funzionalità è qualcosa che probabilmente utilizzerai.

Ecco alcune domande da tenere a mente durante il processo di revisione del codice:

  • Lo vogliamo in TensorFlow? È probabile che venga utilizzato? Come utente TensorFlow, ti piace il cambiamento e intendi utilizzarlo? Questo cambiamento riguarda l'ambito di TensorFlow? Il costo di mantenimento di una nuova funzionalità varrà i suoi benefici?
  • Il codice è coerente con l'API TensorFlow? Le funzioni, le classi e i parametri pubblici hanno nomi appropriati e sono progettati in modo intuitivo?

  • Include la documentazione? Tutte le funzioni pubbliche, le classi, i parametri, i tipi restituiti e gli attributi archiviati sono denominati in base alle convenzioni di TensorFlow e chiaramente documentati? Le nuove funzionalità sono descritte nella documentazione di TensorFlow e illustrate con esempi, quando possibile? La documentazione viene visualizzata correttamente?

  • Il codice è leggibile dall'uomo? La ridondanza è bassa? I nomi delle variabili dovrebbero essere migliorati per chiarezza o coerenza? È opportuno aggiungere commenti? Eventuali commenti dovrebbero essere rimossi perché inutili o estranei?

  • Il codice è efficiente? Potrebbe essere riscritto facilmente per funzionare in modo più efficiente?

  • Il codice è retrocompatibile con le versioni precedenti di TensorFlow?

  • Il nuovo codice aggiungerà nuove dipendenze da altre librerie?

Testare e migliorare la copertura dei test

I test unitari di alta qualità sono una pietra miliare del processo di sviluppo di TensorFlow. A questo scopo utilizziamo immagini Docker. Le funzioni di test hanno un nome appropriato e sono responsabili del controllo della validità degli algoritmi e delle diverse opzioni del codice.

Tutte le nuove funzionalità e le correzioni di bug devono includere un'adeguata copertura dei test. Accogliamo con favore anche contributi di nuovi casi di test o miglioramenti ai test esistenti. Se scopri che i nostri test esistenti non sono completi, anche se ciò non causa attualmente un bug, invia un problema e, se possibile, una richiesta pull.

Per i dettagli specifici delle procedure di test in ciascun progetto TensorFlow, consulta i file README.md e CONTRIBUTING.md nel repository del progetto su GitHub.

Di particolare interesse per i test adeguati :

  • Ogni funzione e classe pubblica viene messa alla prova?
  • Viene testato un insieme ragionevole di parametri , i relativi valori, tipi di valore e combinazioni?
  • I test confermano che il codice è corretto e che sta facendo ciò che la documentazione dice che il codice è destinato a fare?
  • Se la modifica riguarda la correzione di un bug, è incluso un test di non regressione ?
  • I test superano la build di integrazione continua ?
  • I test coprono ogni riga di codice? In caso negativo, le eccezioni sono ragionevoli ed esplicite?

Se riscontri problemi, considera l'idea di aiutare il contributore a comprenderli e risolverli.

Migliorare i messaggi di errore o i log

Accogliamo con favore i contributi che migliorano i messaggi di errore e la registrazione.

Flusso di lavoro del contributo

I contributi al codice (correzioni di bug, nuovi sviluppi, miglioramenti dei test) seguono tutti un flusso di lavoro incentrato su GitHub. Per partecipare allo sviluppo di TensorFlow, configura un account GitHub. Poi:

  1. Effettua il fork del repository su cui prevedi di lavorare. Vai alla pagina del repository del progetto e utilizza il pulsante Fork . Questo creerà una copia del repository, sotto il tuo nome utente. (Per maggiori dettagli su come creare un fork di un repository, consultare questa guida .)

  2. Clona il repository sul tuo sistema locale.

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

  3. Crea un nuovo ramo per conservare il tuo lavoro.

    $ git checkout -b new-branch-name

  4. Lavora sul tuo nuovo codice. Scrivi ed esegui test.

  5. Applica le tue modifiche.

    $ git add -A

    $ git commit -m "commit message here"

  6. Invia le modifiche al repository GitHub.

    $ git push origin branch-name

  7. Aprire una richiesta pull (PR). Vai al repository del progetto originale su GitHub. Verrà visualizzato un messaggio relativo al ramo recentemente inviato, che ti chiederà se desideri aprire una richiesta pull. Segui le istruzioni, confronta i repository e invia il PR. Questo invierà un'e-mail ai committer. Potresti prendere in considerazione l'idea di inviare un'e-mail alla mailing list per maggiore visibilità. (Per maggiori dettagli, consultare la guida GitHub sui PR .

  8. I manutentori e gli altri contributori esamineranno il tuo PR . Partecipa alla conversazione e prova ad apportare le modifiche richieste . Una volta approvato il PR, il codice verrà unito.

Prima di lavorare sul tuo prossimo contributo , assicurati che il tuo repository locale sia aggiornato.

  1. Imposta il telecomando a monte. (Devi farlo solo una volta per progetto, non ogni volta.)

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

  2. Passare al ramo master locale.

    $ git checkout master

  3. Eliminare le modifiche da monte.

    $ git pull upstream master

  4. Invia le modifiche al tuo account GitHub. (Facoltativo, ma è una buona pratica.)

    $ git push origin master

  5. Crea una nuova filiale se stai iniziando un nuovo lavoro.

    $ git checkout -b branch-name

Risorse git e GitHub aggiuntive:

Lista di controllo dei contributori