Contribuisci al codice TensorFlow

Sia che tu stia aggiungendo una funzione di perdita, migliorando la copertura del test o scrivendo un RFC per una modifica importante del design, questa parte della guida per i contributori ti aiuterà a iniziare. Grazie per il lavoro e l'interesse nel migliorare TensorFlow.

Prima di iniziare

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

Per evitare la duplicazione del lavoro, rivedere le RFC attuali o proposte e contattare gli sviluppatori sui forum di TensorFlow ( developers@tensorflow.org ) prima di iniziare a lavorare su una funzione non banale. Siamo alquanto 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 durante la ricerca di un primo contributo alla base di codice di TensorFlow. Raccomandiamo vivamente che i nuovi contributori affrontino prima i progetti "buona prima edizione" e "contributi benvenuti"; questo aiuta il contributore a familiarizzare con il flusso di lavoro del contributo e gli sviluppatori principali a familiarizzare con il contributore.

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

Revisione del codice

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

La revisione del codice ha 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 funzione è 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 la modifica e intendi utilizzarla? Questa modifica rientra nell'ambito di TensorFlow? Il costo del mantenimento di una nuova funzionalità varrà i suoi vantaggi?
  • Il codice è coerente con l'API TensorFlow? Le funzioni, le classi e i parametri pubblici sono ben denominati e progettati in modo intuitivo?

  • Include 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 sono chiaramente documentati? La nuova funzionalità è descritta nella documentazione di TensorFlow e illustrata con esempi, quando possibile? La documentazione è resa correttamente?

  • Il codice è leggibile dall'uomo? Ha poca ridondanza? I nomi delle variabili dovrebbero essere migliorati per chiarezza o coerenza? Dovrebbero essere aggiunti commenti? Eventuali commenti dovrebbero essere rimossi in quanto inutili o estranei?

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

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

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

Testare e migliorare la copertura dei test

Il test unitario di alta qualità è una pietra miliare del processo di sviluppo di TensorFlow. A tale scopo, utilizziamo le immagini Docker. Le funzioni di test sono opportunamente denominate e sono responsabili del controllo della validità degli algoritmi e delle diverse opzioni del codice.

Tutte le nuove funzionalità e 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 sta attualmente causando un bug, segnala un problema e, se possibile, una richiesta pull.

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

Di particolari preoccupazioni in test adeguati :

  • Ogni funzione pubblica e classe è verificata?
  • Un insieme ragionevole di parametri , i relativi valori, tipi di valori e combinazioni sono testati?
  • I test convalidano che il codice sia corretto e che stia facendo ciò che la documentazione dice che il codice è destinato a fare?
  • Se la modifica è una correzione di 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 di aiutare il collaboratore a comprenderli e risolverli.

Migliora i messaggi di errore o i registri

Diamo il benvenuto a contributi che migliorano i messaggi di errore e la registrazione.

Flusso di lavoro del contributo

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

  1. Effettua il fork del repository su cui intendi lavorare. Vai alla pagina del repository del progetto e usa il pulsante Fork . Questo creerà una copia del repository, sotto il tuo nome utente. (Per maggiori dettagli su come eseguire il fork di un repository, consulta 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 tenere il tuo lavoro.

    $ git checkout -b new-branch-name

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

  5. Conferma 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. Apri una richiesta pull (PR). Vai al repository del progetto originale su GitHub. Verrà visualizzato un messaggio sul ramo inviato di recente, che ti chiederà se desideri aprire una richiesta pull. Segui le istruzioni, confronta tra i repository e invia la PR. Questo invierà un'e-mail ai committenti. Potresti prendere in considerazione l'invio di un'e-mail alla mailing list per una maggiore visibilità. (Per maggiori dettagli, consulta la guida GitHub sui PR .

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

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

  1. Impostare 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. Passa al ramo principale locale.

    $ git checkout master

  3. Tira giù 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 un nuovo ramo se stai iniziando un nuovo lavoro.

    $ git checkout -b branch-name

Risorse aggiuntive su git e GitHub:

Lista di controllo dei collaboratori