Panoramica

Tutte le modifiche al codice e alla documentazione devono essere inviate tramite una richiesta di pull al repository di GitHub per il progetto.

La maggior parte dei progetti ha una guida dedicata ai contributi con dettagli specifici al progetto o a tipi specifici di contributo. Questa documentazione può essere trovata su Read the Docs. Per esempio, la documentazione di Briefcase documentazione contiene guide ai contributi per entrambi i progetti codice e documentazione.

Tutti gli invii devono rispettare il Codice di condotta BeeWare. Condotta] (/comunità/comportamento/codice di condotta/).

Note di modifica

Diversi progetti BeeWare, in particolare Briefcase e Toga, richiedono che ogni richiesta di richiesta di pull sia accompagnata da una nota di modifica. Queste note di modifica vengono compilate insieme quando viene tagliata una nuova release per il progetto, producendo così le le note di rilascio per la nuova release.

BeeWare utilizza Towncrier per gestire le note di modifica.

Un file di note di modifica deve essere creato nella directory changes e e nominato utilizzando questo formato:

<PR/Issue #>.<Tipo di modifica>.rst

Per esempio, una richiesta di pull che risolve il problema GitHub #42 si chiamerà 42.bugfix.rst. Se una richiesta di pull non è associata a una specifica problema specifico, si può usare il numero della richiesta di pull. Potrebbe essere necessario creare la richiesta di pull senza una nota di modifica per ottenere un numero di richiesta di pull per ottenere l'assegnazione di un numero di richiesta di pull, quindi inviare un aggiornamento che includa la nota di modifica con il numero di richiesta di pull appena assegnato.

Il tipo di modifica per la nota di modifica deve essere uno dei seguenti:

  • caratteristiche
  • bugfix
  • doc
  • rimozione
  • misc

Il tipo misc è riservato alle modifiche che non hanno effetto sugli utenti e che non devono essere non hanno bisogno di essere segnalate nelle note di rilascio. Correzioni tipografiche minori nella documentazione, aggiornamenti alla configurazione del CI e correzioni di bug per funzionalità che non sono ancora state che non sono ancora state rilasciate ufficialmente sono esempi di caratteristiche che potrebbero essere descritte con i marcatori misc.

Una nota di modifica dovrebbe essere una singola riga di testo, che fornisca un riassunto di alto livello della di alto livello della modifica dal punto di vista dell'utente, non una profonda descrizione tecnica o di dettagli di implementazione. Si distingue da un messaggio di commit. Un messaggio di commit descrive ciò che è stato fatto in modo che gli futuri sviluppatori possano seguire il ragionamento di una modifica. Una nota di modifica è una descrizione "rivolta all'utente", descritta in termini di nuova funzionalità che è disponibile come risultato della modifica. Può essere utile pensare alla nota di modifica come un comunicato stampa che annuncia la modifica, piuttosto che come una descrizione del commit.

Per esempio, se si corregge un bug causato dalla gestione della data, il messaggio di commit o la descrizione della richiesta di pull potrebbero essere o la descrizione della richiesta di pull potrebbero recitare:

Aggiunto un validatore del formato MM-DD-YYYY alla catena di validazione di DateWidget. catena.

Descrive la modifica apportata all'implementazione - dettagli che sarà utile a chi sta revisionando il codice. Tuttavia, la corrispondente nota di modifica potrebbe essere qualcosa di simile a:

I widget di data possono ora accettare date in formato USA.

Descrive il cambiamento funzionale come sarà vissuto dagli utenti finali. utenti finali. Un utente può leggere questa descrizione senza dover conoscere nulla dell'implementazione.

Codice stile

I progetti di BeeWare utilizzano Pre-commit per automatizzare l'aderenza allo stile del codice. Questi controlli sono definiti nel file file .pre-commit-config.yaml per ogni repository e vengono automaticamente in CI quando viene aperta una richiesta di pull. viene aperta.

Per automatizzare i controlli di Pre-commit nell'ambiente di sviluppo locale a ogni commit di git, eseguire pre-commit install.

Controlli pre-commit inclusi:

  • Nero assicura una formattazione uniforme del codice
  • docformatter assicura una formattazione una formattazione uniforme per le documentazioni e i commenti
  • pyupgrade assicura che il codice sia utilizzando le più recenti best practice per Python
  • isort assicura l'uniformità delle dichiarazioni di import uniforme
  • flake8 controlla i problemi comuni di codifica e di sintassi. e sintassi
  • Controlli vari che convalidano i documenti strutturati, come i file TOML e rimuovono gli spazi bianchi non necessari

Linee guida aggiuntive:

  • Evitare l'uso del "noi" nei commenti, ad esempio "Loop over" piuttosto che "We loop over". sopra"

  • Usare i trattini bassi, non il camelCase, per i nomi di variabili, funzioni e metodi. e metodi

  • Usare InitialCaps per i nomi delle classi (o per le funzioni di fabbrica che restituiscono classi)

  • Use Sphinx-style docstrings and PEP 257; type annotation with PEP 484 is optional but encouraged.

    Ad esempio:

    def nome_funzione(param1: int, param2: str) -> bool:
    """Esempio di funzione con tipi e una docstring.

    :param param1: Il primo parametro.
    :param2: Il secondo parametro.

    :ritorna: Il valore di ritorno. Vero in caso di successo, Falso in caso contrario.
    """

  • Nelle documentazioni dei test, dichiarare il comportamento atteso che ogni test dimostra. Non includere preamboli come "Verifica che" o "Assicura che". che".

  • Riservare i riferimenti ai ticket per i problemi oscuri in cui il ticket ha dettagli aggiuntivi che non possono essere facilmente descritti nei documenti o nei commenti. commenti. Includere il numero del ticket alla fine di una frase del tipo questo:

    def test_foo():
    """Una docstring di test assomiglia a questa (#123456)""".

  • Unless otherwise specified, follow PEP 8 (with careful attention paid to Section 2).