Guida per i collaboratori

Se state leggendo questa pagina probabilmente siete interessati a contribuire a Requests. Come prima cosa, vi diciamo: grazie! I progetti open source vivono e muoiono sul supporto che ricevono dalle altre persone, e il fatto stesso che stiate considerando di supportare Requests è molto generoso da parte vostra.

Questo documento individua alcune linee guida e alcuni consigli per contribuire a Requests. Se state considerando di contribuire, cominciate a leggere bene questo documento e a farvi un’idea di come si fa a contribuire al progetto. Per ogni domanda, sentitevi liberi di contattare Ian Cordasco o Cory Benfield, i maintainer principali.

Questa guida è divisa in sezioni sulla tipologia di contributo che state considerando di fare, con una sezione che tratta le linee guida generali per tutti i collaboratori.

Per tutti i tipi di contributi

Siate cordiali

Siate cordiali o state lontani.

Requests ha una regola importante che governa tutte le tipologie di contributo, inclusi i bug report o le richieste di nuove feature. Questa regola d’oro è siate cordiali o state lontani. Tutti i contributi sono bene accetti, fintanto che tutte le persone coinvolte vengono trattate con rispetto.

Cercate un feedback rapido

Se contribuite, non mantenete privato il vostro lavoro fino a che non è perfetto e completo. Se cercate di avere feedback sul vostro lavoro il prima possible, date una mano a tutti. Inviare una versione draft e incompleta del vostro lavoro per ottenere feedback non pregiudicherà in alcun modo le vostre chance di ottenere che esso venga accettato, anzi può evitarvi di fare un mucchio di lavoro su un contributo che in realtà potrebbe non essere adatto al progetto.

Idoneità dei contributi

Il project maintainer ha l’ultima parola sull’idoneità di un contributo al progetto Requests. Tutti i contributi saranno considerati, ma certe volte capiterà che alcuni contributi saranno rigettati perchè non sono adatti al progetto.

Se il vostro contributo viene rigettato, non disperate! Se avete seguito queste linee guida avrete la miglior chance di vedere accettato il vostro prossimo contributo.

Contributi al codice

Passi

Se contribuite al codice, servitevi di questa checklist:

  1. Forkate il repository su GitHub.
  2. Fate girare i test per stabilire se passano tutti nel vostro ambiente. In caso negativo, cercate di capire perchè falliscono. Se non riuscite a capirlo da soli, compilate un bug report seguendo i passi descritti in questo documento: Bug Report.
  3. Scrivete dei test che dimostrino l’esistenza del baco o la mancanza della nuova feature. Accertatevi che questi test falliscano.
  4. Apportate le vostre modifiche al codice.
  5. Fate girare di nuovo l’intera test suite, avendo conferma che tutti i test passano inclusi quelli che avete aggiunto in precedenza.
  6. Inviate una Pull Request su GitHub sulla master branch del repository principale. Le Pull Requests di GitHub sono il metodo che usiamo nel progetto per inviare i contributi di codice.

Le prossime sottosezioni entrano più in dettaglio su alcuni dei punti sopra illustrati.

Revisione del codice

I contributi non saranno mergiati nella codebase finchè il codice non sarà rivisto. Dovreste implementare ogni feedback che ricevete a livello di revisione del codice, a meno che non siate in forte disaccordo con essi. In tale caso, dovreste spiegare il perchè in maniera chiara e pacata. Se, anche dopo averlo fatto, il feedback non viene modificate, potete o implementare il feedback oppure ritirare il vostro contributo.

Nuovi collaboratori

Se non vi siete mai accostati all’Open Source o siete relativamente nuovi, benvenuti! Requests vuol essere un’introduzione gentile al mondo dell’Open Source. Se siete indecisi su come contribuire al meglio, perfavore prendete in considerazione di mandare una e-mail ad uno dei maintainer (riportati sopra) e chiedere aiuto.

Leggete anche la sezione Cercate un feedback rapido.

Contributi alla documentazione

Le migliorie alla documentazione sono sempre benvenute! I file della documentazione risiedono nella cartella docs/ della codebase. Sono scritti in reStructuredText, e utilizziamo Sphinx per generare l’intero corpo della documentazione.

Quando contribuite alla documentazione, siete pregati di seguirne lo stile. Ciò significa un limite di 79 colonne nei file di testo e uno stile di prosa semi-formale.

Bug Report

I bug report sono di vitale importanza! Prima di notificare un bug, perfavore leggete le issues di GitHub, sia quelle aperte che quelle chiuse, per avere conferma che il baco non sia già stato segnalato in passato. I bug report duplicati sono una grossa perdita di tempo per gli altri collabortori e dovrebbero essere assolutamente evitati.

Richiesta di nuove feature

Requests è in un perpetuo stato di congelamento delle feature. I maintainers credono che la libreria contenga tutte le principali feature utili alla stragrande maggioranza degli utenti.

Se credete che manchi una feature, siate liberi di inviare una richiesta ma sappiate che con ogni probabilità la richiesta non sarà accettata.