Il processo TensorFlow RFC

Ogni nuova funzionalità di TensorFlow inizia come una richiesta di commento (RFC).

Un RFC è un documento che descrive un requisito e le modifiche proposte che lo risolveranno. In particolare, l'RFC:

  • Essere formattato in base al modello RFC .
  • Essere inviato come richiesta pull alla directory community / rfcs .
  • Essere oggetto di discussione e di una riunione di revisione prima dell'accettazione.

Lo scopo di una richiesta di commenti (RFC) di TensorFlow è coinvolgere la comunità di TensorFlow nello sviluppo, ottenendo feedback dalle parti interessate e dagli esperti e comunicando ampiamente le modifiche di progettazione.

Come inviare una RFC

  1. Prima di inviare una RFC, discuti i tuoi obiettivi con i contributori e i manutentori del progetto e ottieni un feedback tempestivo. Usa la mailing list degli sviluppatori per il progetto in questione (developers@tensorflow.org, o la lista per il SIG pertinente).

  2. Crea la tua RFC.

    • Leggi i criteri di revisione del progetto
    • Segui il modello RFC .
    • Assegna un nome al file RFC YYYYMMDD-descriptive-name.md , dove YYYYMMDD è la data di invio e il descriptive-name riferisce al titolo della tua RFC. (Ad esempio, se la tua RFC è denominata API Parallel Widgets , potresti utilizzare il nome file 20180531-parallel-widgets.md .
    • Se si dispone di immagini o altri file ausiliari, creare una directory nel formato YYYYMMDD-descriptive-name in cui memorizzare quei file.

    Dopo aver scritto la bozza RFC, ottieni feedback dai manutentori e dai contributori prima di inviarla.

    La scrittura del codice di implementazione non è un requisito, ma può aiutare a progettare le discussioni.

  3. Recluta uno sponsor.

    • Uno sponsor deve essere un manutentore del progetto.
    • Identifica lo sponsor nella RFC, prima di pubblicare il PR.

    Inserire un RFC senza sponsor, ma se entro un mese dalla pubblicazione del PR non c'è ancora sponsor, sarà chiuso.

  4. Invia la tua RFC come richiesta pull a tensorflow / community / rfcs .

    Includere la tabella di intestazione e il contenuto della sezione Obiettivo nel commento della richiesta pull, utilizzando Markdown. Per un esempio, vedere questo esempio RFC . Includere gli handle di GitHub di coautori, revisori e sponsor.

    Nella parte superiore del PR, identifica la durata del periodo di commento. Questo dovrebbe essere un minimo di due settimane dalla pubblicazione del PR.

  5. Inviare un'e-mail alla mailing list degli sviluppatori con una breve descrizione, un collegamento al PR e una richiesta di revisione. Segui il formato degli invii precedenti, come puoi vedere in questo esempio .

  6. Lo sponsor richiederà una riunione del comitato di revisione non prima di due settimane dopo la pubblicazione dell'RFC PR. Se la discussione è vivace, attendere che si sia risolta prima di passare alla revisione. L'obiettivo della riunione di revisione è risolvere i problemi minori; il consenso dovrebbe essere raggiunto in anticipo sulle principali questioni.

  7. La riunione può approvare la RFC, rifiutarla o richiedere modifiche prima che possa essere nuovamente presa in considerazione. Le RFC approvate verranno unite in community / rfcs e le RFC rifiutate avranno i loro PR chiusi.

Partecipanti RFC

Molte persone sono coinvolte nel processo RFC:

  • Autore RFC : uno o più membri della comunità che scrivono un RFC e si impegnano a sostenerlo durante il processo

  • Sponsor RFC : un manutentore che sponsorizza l'RFC e lo guiderà attraverso il processo di revisione dell'RFC

  • comitato di revisione - un gruppo di manutentori che hanno la responsabilità di raccomandare l'adozione della RFC

  • Qualsiasi membro della comunità può aiutare fornendo un feedback sul fatto che l'RFC soddisferà le loro esigenze.

Sponsor RFC

Uno sponsor è un responsabile del progetto responsabile di garantire il miglior risultato possibile del processo RFC. Ciò comprende:

  • Sostenere il progetto proposto.
  • Guidare l'RFC ad aderire alle convenzioni di design e stile esistenti.
  • Guidare il comitato di revisione a raggiungere un consenso produttivo.
  • Se il comitato di revisione richiede modifiche, assicurarsi che vengano apportate e richiedere la successiva approvazione dei membri del comitato.
  • Se l'RFC passa all'implementazione:
    • Garantire che l'implementazione proposta aderisca al progetto.
    • Coordinarsi con le parti appropriate per implementare con successo il terreno.

Comitati di revisione RFC

Il comitato di revisione decide in base al consenso se approvare, rifiutare o richiedere modifiche. Sono responsabili di:

  • Garantire che gli elementi sostanziali del feedback pubblico siano stati tenuti in considerazione.
  • Aggiungere le note della riunione come commenti al PR.
  • Fornire ragioni per le loro decisioni.

La costituzione di un comitato di revisione può cambiare in base al particolare stile di governance e alla leadership di ogni progetto. Per il core TensorFlow, il comitato sarà composto da contributori al progetto TensorFlow che hanno esperienza nell'area del dominio interessata.

Membri della comunità e processo RFC

Lo scopo delle RFC è garantire che la comunità sia ben rappresentata e servita dalle nuove modifiche a TensorFlow. È responsabilità dei membri della comunità partecipare alla revisione delle RFC laddove hanno un interesse per il risultato.

I membri della comunità interessati a una RFC dovrebbero:

  • Fornire un feedback il prima possibile per consentire un tempo adeguato per la considerazione.
  • Leggere attentamente le RFC prima di fornire feedback.
  • Sii civile e costruttivo .

Implementazione di nuove funzionalità

Una volta che una RFC è stata approvata, può iniziare l'implementazione.

Se stai lavorando su un nuovo codice per implementare un RFC:

  • Assicurati di comprendere la funzionalità e il design approvato nella RFC. Poni domande e discuti l'approccio prima di iniziare il lavoro.
  • Le nuove funzionalità devono includere nuovi unit test che verificano che la funzionalità funzioni come previsto. È una buona idea scrivere questi test prima di scrivere il codice.
  • Segui la guida allo stile del codice TensorFlow
  • Aggiungi o aggiorna la documentazione API pertinente. Fare riferimento alla RFC nella nuova documentazione.
  • Segui tutte le altre linee guida stabilite nel file CONTRIBUTING.md nel repository del progetto a cui stai contribuendo.
  • Esegui test unitari prima di inviare il codice.
  • Collaborare con lo sponsor RFC per ottenere con successo il nuovo codice.

Tenere alto il livello

Sebbene incoraggiamo e celebriamo ogni collaboratore, il livello di accettazione dell'RFC viene mantenuto intenzionalmente alto. Una nuova funzionalità può essere rifiutata o richiedere una revisione significativa in una di queste fasi:

  • Conversazioni di progettazione iniziali sulla mailing list pertinente.
  • Mancato reclutamento di uno sponsor.
  • Obiezioni critiche durante la fase di feedback.
  • Mancato raggiungimento del consenso durante la revisione del progetto.
  • Preoccupazioni sollevate durante l'implementazione (ad esempio: incapacità di ottenere la compatibilità con le versioni precedenti, preoccupazioni sulla manutenzione).

Se questo processo funziona bene, ci si aspetta che le RFC falliscano nelle fasi precedenti, piuttosto che successive. Una RFC approvata non è garanzia di un impegno da implementare e l'accettazione di una proposta di implementazione RFC è ancora soggetta al consueto processo di revisione del codice.

In caso di domande su questo processo, non esitare a chiedere nella mailing list degli sviluppatori o a presentare un problema in tensorflow / community .