Il processo TensorFlow RFC

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

Una RFC è un documento che descrive un requisito e le modifiche proposte che lo risolveranno. Nello specifico, la RFC:

  • Essere formattato secondo il modello RFC .
  • Essere inviato come richiesta pull alla directory community/rfcs .
  • Essere soggetto a discussione e a un incontro di revisione prima dell'accettazione.

Lo scopo di una TensorFlow Request for Comments (RFC) è coinvolgere la community di TensorFlow nello sviluppo, ottenendo feedback dalle parti interessate e dagli esperti e comunicando ampiamente le modifiche alla 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. Utilizzare la mailing list degli sviluppatori per il progetto in questione (developers@tensorflow.org o l'elenco per il SIG pertinente).

  2. Redige 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 descriptive-name si riferisce al titolo della tua RFC. (Ad esempio, se la tua RFC è intitolata Parallel Widgets API , potresti utilizzare il nome file 20180531-parallel-widgets.md .
    • Se disponi di immagini o altri file ausiliari, crea una directory nel formato YYYYMMDD-descriptive-name in cui archiviare tali file.

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

    Scrivere il codice di implementazione non è un requisito, ma può aiutare a progettare le discussioni.

  3. Recluta uno sponsor.

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

    Puoi pubblicare una RFC senza sponsor, ma se entro un mese dalla pubblicazione della PR non c'è ancora nessuno sponsor, verrà chiusa.

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

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

    Nella parte superiore del PR identifica la durata del periodo di commento. Dovrebbero trascorrere almeno due settimane dalla pubblicazione del PR.

  5. Invia 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 dalla pubblicazione del PR RFC. Se la discussione è vivace, aspetta che si sia calmata prima di passare alla revisione. L'obiettivo della riunione di revisione è risolvere problemi minori; il consenso dovrebbe essere raggiunto in anticipo sulle questioni più importanti.

  7. L'assemblea può approvare la RFC, respingerla 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 alla RFC

Molte persone sono coinvolte nel processo RFC:

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

  • Sponsor RFC : un manutentore che sponsorizza la RFC e la guiderà attraverso il processo di revisione della 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 feedback sulla capacità della RFC di soddisfare le proprie esigenze.

Sponsor della RFC

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

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

Comitati di revisione RFC

Il comitato di revisione decide su base consensuale se approvare, respingere o richiedere modifiche. Sono responsabili di:

  • Garantire che si tenga conto dei feedback sostanziali del pubblico.
  • Aggiunta delle note della riunione come commenti al PR.
  • Motivare le proprie decisioni.

La costituzione di un comitato di revisione può cambiare a seconda del particolare stile di governance e leadership di ciascun 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 abbiano interesse al risultato.

I membri della comunità interessati a una RFC dovrebbero:

  • Fornire feedback il prima possibile per concedere tempo adeguato per la considerazione.
  • Leggere attentamente le RFC prima di fornire feedback.
  • Siate civili e costruttivi .

Implementazione di nuove funzionalità

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

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

  • Assicurati di comprendere la funzionalità e il design approvati nella RFC. Porre domande e discutere l'approccio prima di iniziare il lavoro.
  • Le nuove funzionalità devono includere nuovi test unitari che verifichino 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 qualsiasi altra linea guida stabilita nel file CONTRIBUTING.md nel repository del progetto a cui stai contribuendo.
  • Esegui unit test prima di inviare il codice.
  • Collaborare con lo sponsor RFC per ottenere con successo il nuovo codice.

Mantenere l'asticella alta

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

  • Conversazioni iniziali di progettazione sulla mailing list pertinente.
  • Mancata 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, è probabile che le RFC falliscano nelle fasi precedenti, anziché successive. Una RFC approvata non è garanzia di un impegno da implementare e l'accettazione di un'implementazione RFC proposta è ancora soggetta al consueto processo di revisione del codice.

Se hai domande su questo processo, non esitare a chiedere alla mailing list degli sviluppatori o ad inviare un problema in tensorflow/community .