Contribuisci al codice TensorFlow

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

Prima di iniziare

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

Per evitare di duplicare il lavoro, vi preghiamo di consultare le RFC attuali o proposte e di contattare 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 collaboratori

I nuovi collaboratori dovrebbero cercare i seguenti tag quando cercano un primo contributo alla base di codice di TensorFlow. Consigliamo vivamente ai nuovi collaboratori di affrontare prima i progetti "buon primo numero" e "contributi benvenuti"; questo aiuta il collaboratore a familiarizzare con il flusso di lavoro di contributo e aiuta gli sviluppatori principali a familiarizzare con il collaboratore.

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

Revisione del codice

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

La revisione del codice inviato al progetto tramite pull request è una componente fondamentale dello sviluppo di TensorFlow. Incoraggiamo chiunque a iniziare a revisionare il codice inviato da altri sviluppatori, soprattutto se si tratta di una funzionalità che probabilmente utilizzerete.

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

  • Vogliamo che questa funzionalità venga implementata in TensorFlow? È probabile che venga utilizzata? Come utente di TensorFlow, apprezzi la modifica e intendi utilizzarla? Questa modifica rientra nell'ambito di applicazione di TensorFlow? Il costo di mantenimento di una nuova funzionalità varrà i suoi vantaggi?
  • Il codice è coerente con l'API di TensorFlow? Le funzioni, le classi e i parametri pubblici sono ben denominati e progettati in modo intuitivo?

  • Include la documentazione? Tutte le funzioni pubbliche, le classi, i parametri, i tipi di ritorno e gli attributi memorizzati sono denominati secondo le convenzioni di TensorFlow e chiaramente documentati? Le nuove funzionalità sono descritte nella documentazione di TensorFlow e illustrate con esempi, ove possibile? La documentazione viene visualizzata correttamente?

  • Il codice è leggibile? È poco ridondante? I nomi delle variabili dovrebbero essere migliorati per maggiore chiarezza o coerenza? Bisognerebbe aggiungere commenti? I commenti dovrebbero essere rimossi perché inutili o superflui?

  • 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

Test unitari di alta qualità sono un pilastro del processo di sviluppo di TensorFlow. A questo scopo, utilizziamo immagini Docker. Le funzioni di test hanno nomi appropriati e sono responsabili della verifica della validità degli algoritmi e delle diverse opzioni del codice.

Tutte le nuove funzionalità e le correzioni di bug devono includere un'adeguata copertura di 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 causando un bug, ti preghiamo di segnalare un problema e, se possibile, di inviare una pull request.

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

Di particolare preoccupazione per quanto riguarda i test adeguati :

  • Ogni funzione e classe pubblica viene testata?
  • Sono stati testati un insieme ragionevole di parametri , i loro valori, i tipi di valore e le combinazioni?
  • I test convalidano che il codice è corretto e che sta facendo ciò che la documentazione afferma 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 contrario, le eccezioni sono ragionevoli ed esplicite?

Se riscontri dei problemi, ti preghiamo di aiutare il collaboratore a comprenderli e a risolverli.

Migliorare i messaggi di errore o i registri

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

Flusso di lavoro dei contributi

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, crea un account GitHub. Quindi:

  1. Crea un 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, con il tuo nome utente. (Per maggiori dettagli su come creare un 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 in cui archiviare 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 tuo repository GitHub.

    $ git push origin branch-name

  7. Apri una Pull Request (PR). Vai al repository originale del progetto su GitHub. Ti verrà mostrato un messaggio relativo al tuo branch appena caricato, che ti chiederà se desideri aprire una pull request. Segui le istruzioni, confronta i repository e invia la PR. Questo invierà un'email ai committer. Potresti valutare di inviare un'email alla mailing list per una maggiore visibilità. (Per maggiori dettagli, consulta la guida GitHub sulle PR .

  8. I manutentori e gli altri collaboratori esamineranno la tua richiesta di pubblicazione . Partecipa alla conversazione e prova ad apportare le modifiche richieste . Una volta approvata la richiesta, il codice verrà integrato.

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

  1. Imposta il remote upstream. (È necessario eseguire questa operazione 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. Estrarre le modifiche dall'upstream.

    $ 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 del collaboratore