Aggiunta di documentazione¶

Potreste avere il miglior software del mondo, ma se nessuno sa come usarlo, che senso ha? La documentazione può sempre essere migliorata e abbiamo bisogno del vostro aiuto!

Moduli di documentazione¶

La documentazione di {{ nome_formale }} è scritta utilizzando MkDocs e Markdown. Il nostro obiettivo è seguire il framework Diataxis per la strutturazione della documentazione.

Il quadro di Diataxis descrive quattro "forme" di documentazione:

Tutorial - Un'esperienza di apprendimento guidata, con uno specifico obiettivo di progetto.
Guida - Istruzioni che guidano il lettore verso un obiettivo o un risultato specifico.
Guida tematica - Discussione di una singola idea, spiegata in modo tale che i concetti sottostanti siano chiari.
Riferimenti - Descrizioni tecniche di specifiche API o altre interfacce.

Prima di iniziare qualsiasi contributo alla documentazione, è importante identificare la forma più adatta. Molte proposte di documentazione vengono inizialmente descritte come una richiesta di "un tutorial su X", ma nella maggior parte dei casi ciò che viene richiesto è un manuale di istruzioni, una guida agli argomenti o una migliore informazione di riferimento.

A titolo di esempio, si consideri il compito di scrivere una documentazione sulla preparazione dei biscotti.

Tutorial¶

Un tutorial è un'introduzione, in particolare per i principianti, il cui obiettivo dovrebbe essere quello di portare il lettore da un punto di partenza pulito a un prodotto finito. Richiede istruzioni molto specifiche e spiegazioni dettagliate che contestualizzino le fasi del tutorial. Non si deve dare per scontata l'esperienza del lettore con lo strumento spiegato, anche se è ragionevole ipotizzare una certa conoscenza di base di Python.

Il tutorial deve contenere punti di controllo regolari in cui il lettore possa stabilire se è riuscito a fare ciò che è stato descritto. In ogni punto di controllo, i criteri di successo devono essere chiari. I casi di insuccesso noti devono essere chiaramente delineati, con spiegazioni di eventuali errori o problemi che il lettore potrebbe riscontrare. Le cose che cambiano in seguito alle azioni intraprese dal lettore devono essere evidenziate, anche se apparentemente ovvie. La ripetizione è incoraggiata, soprattutto se si sta cercando di stabilire una best practice o processi comuni. Le spiegazioni degli aspetti interni devono essere evitate, così come i percorsi alternativi per ottenere lo stesso risultato.

Un tutorial sulla preparazione dei biscotti è più di una semplice ricetta. Le istruzioni di un tutorial dovrebbero essere accessibili a chi non ha mai cucinato prima (ad esempio un bambino) e dovrebbero tenere conto di aspetti che un panettiere esperto darebbe per scontati, come ad esempio la preparazione della crema di zucchero e burro, il processo di preriscaldamento del forno o il tempo di raffreddamento dei biscotti prima di mangiarli. L'obiettivo del tutorial non è produrre un biscotto, ma trasmettere i fondamenti della cottura. Il biscotto che ne deriva è la delizia che convince qualcuno a seguire il tutorial.

Guida all'uso¶

Una guida su come fare dovrebbe concentrarsi su uno specifico caso d'uso del mondo reale e sui risultati pratici, piuttosto che su spiegazioni teoriche. A differenza di un tutorial, si può presumere una certa familiarità con gli strumenti esistenti. Il lettore dovrebbe essere in grado di seguire la guida dall'inizio alla fine e raggiungere l'obiettivo, ma potrebbe aver bisogno di alcune conoscenze già acquisite per farlo. Dovrebbe includere una serie di istruzioni concrete o di passaggi logici da seguire per raggiungere l'obiettivo della guida.

Una ricetta contenuta in un libro di cucina è un buon esempio di guida alla preparazione. Esistono molte ricette di biscotti con gocce di cioccolato e tutte avranno caratteristiche comuni, ma ogni ricetta specifica dovrebbe poter essere seguita dall'inizio alla fine e dare un risultato coerente. Una buona ricetta di biscotti con gocce di cioccolato non si dilungherà sui meriti relativi dei diversi tipi di zucchero o di farina, né fornirà istruzioni dettagliate sulla tecnica o sul processo di base; includerà solo gli ingredienti e le istruzioni per preparare una partita di biscotti, presumendo che il lettore abbia una familiarità di base con la cottura.

Guida agli argomenti¶

Una guida per argomenti descrive un singolo argomento o idea. Può includere esempi di codice o istruzioni, ma è molto più incentrata sul fornire un quadro di alto livello di un concetto generale. Può includere opinioni e punti di vista alternativi, ma deve mantenere l'attenzione sull'argomento specifico della guida.

Una guida tematica sulla cottura dei biscotti potrebbe approfondire la storia dei biscotti come prodotto da forno, esplorare il modo in cui i processi industriali producono tipi diversi di biscotti rispetto a quelli fatti in casa, o suggerire i modi in cui i biscotti possono essere incorporati in una dieta equilibrata. Di per sé, non sarebbe un documento molto utile da seguire se si volesse preparare un biscotto, ma potrebbe fornire il background che consentirebbe a chi ha familiarità con la cottura di personalizzare con successo una ricetta di biscotti esistente.

Riferimento¶

La documentazione di riferimento è orientata alle informazioni e descrive le specifiche del funzionamento di una libreria di strumenti. Spesso può essere generata dal codice stesso, ma una buona documentazione API può richiedere ulteriori spiegazioni e contesto. Anche se a volte può includere esempi di utilizzo, le spiegazioni dettagliate dovrebbero essere evitate.

Una guida di riferimento per la panificazione potrebbe descrivere i tipi di zucchero che si possono usare e descrivere le loro proprietà quando vengono utilizzati nella panificazione. Si tratterebbe di descrivere i fatti letterali sullo zucchero, ma una discussione più ampia sulla scelta tra i vari tipi di zucchero dovrebbe essere oggetto di una guida su come fare o di una guida tematica. Le informazioni nutrizionali che si trovano sulla maggior parte degli alimenti confezionati sarebbero considerate documentazione di riferimento.

Stile della documentazione¶

La documentazione di {{ nome_formale }} segue le linee guida delineate nella guida allo stile della documentazione. Questa guida include lo stile e la formattazione di base e la procedura per il controllo ortografico. Copre anche vari dettagli della sintassi di Markdown, come la sintassi dei link di riferimento, i suggerimenti per lavorare con i blocchi di codice e la gestione delle immagini.

Contribuire alla documentazione¶

Proposta di nuova documentazione

Hai un'idea su un miglioramento per {{ nome_formale }} - come si fa a sottoporre l'idea alla vostra attenzione?

Fate la vostra ricerca¶

Il primo passo consiste nel cercare nell'issue tracker {{ nome_formale }} i problemi di funzionalità (problemi etichettati come "miglioramento"), documentation issues (problemi con tag "documentation"), o Discussioni per vedere se l'idea è già stata proposta in precedenza. In caso affermativo, se avete un nuovo contesto o nuove idee da aggiungere, inseritele nella discussione esistente. Se si desidera assistenza per la ricerca, è possibile chiedere nel canale #dev su BeeWare Discord. Potremmo essere in grado di indirizzarvi verso le discussioni esistenti, di fornirvi un contesto di cui potreste non essere a conoscenza o di collegare la vostra idea a un'altra che potrebbe non sembrare immediatamente collegata.

Discutere l'idea¶

Se non si trovano riferimenti esistenti alla propria idea, avviare una Discussione. Fornire una descrizione di alto livello dello scopo e del caso d'uso della propria idea. Includere qualsiasi idea sull'aspetto della funzionalità, se implementata, come la forma generale di un'API, l'aspetto visivo di una funzionalità o il documento che verrebbe aggiunto. Se applicabile, è necessario includere anche qualsiasi ricerca effettuata su come la vostra idea si manifesterebbe su piattaforme diverse.

Una volta aperto il thread di discussione, il team BeeWare e il resto della comunità risponderanno. Il team centrale cercherà di fornire almeno un'impressione iniziale della vostra idea entro due giorni lavorativi. Se un'idea è particolarmente complessa, un'analisi più dettagliata potrebbe richiedere fino a una settimana. Eventi come vacanze e conferenze potrebbero allungare leggermente i tempi.

Questa è l'occasione per partecipare a una conversazione sulla vostra idea. Potremmo chiedervi ulteriori dettagli o un contesto. Anche altri membri della comunità possono partecipare alla discussione, fornendo altre prospettive, suggerimenti o controproposte. L'esito della discussione determinerà i passi successivi.

È importante capire che non tutte le idee saranno accettate. Il motivo per cui questo processo inizia con una proposta è che si evita di fare tutto il lavoro per poi scoprire che la modifica non sarà accettata.

Questo non significa che non fosse una buona idea! Ci possono essere ragioni tecniche per cui non può essere implementata. Ad esempio, potremmo rifiutare un'idea se:

Sarebbe difficile o impossibile da implementare in modo affidabile su tutte le piattaforme supportate; oppure
Sarebbe difficile da mantenere o la manutenzione richiederebbe l'accesso a tecnologie o software non ampiamente disponibili; oppure
Serve un pubblico di nicchia, ma impone un notevole sovraccarico agli altri utenti.

Se decidiamo che la vostra idea non è adatta, non significa necessariamente che dobbiate rinunciarvi. Se da un lato possiamo rifiutare un'idea specifica, dall'altro potremmo essere molto più disponibili ad aggiungere un'interfaccia per i plugin o altri punti di estensione che permettano di mantenere la stessa funzionalità come libreria esterna. In questo modo si può avere la funzione, ma senza che i problemi specifici di manutenzione o le limitazioni della funzione diventino un vincolo per il progetto stesso.

Convertite in una richiesta formale di funzionalità¶

Una volta che la discussione ha raggiunto un consenso sulla forma di una caratteristica, si può creare un nuovo [issue di richiesta di caratteristica] (https://github.com/beeware/{{ nome_progetto }}/issues/new/choose), nell'issue tracker {{ nome_formale }}, che riassume la discussione, collegandosi alla discussione per il contesto.

Non è necessario implementare da soli la propria proposta di funzionalità; è possibile aprire un problema con i dettagli di ciò che si sta proponendo. Tuttavia, la semplice pubblicazione del problema non significa che verrà implementato per voi. Dovrete aspettare che la proposta venga presa in considerazione da qualcun altro interessato alla stessa funzionalità, che si tratti di un altro membro della comunità o del team centrale; tuttavia non è garantito che ciò accada. Se si desidera un'implementazione garantita, è necessario implementarla da soli o pagare qualcun altro per farlo.

Configurare un ambiente di sviluppo

Contribuire a {{ nome_formale }} richiede la creazione di un ambiente di sviluppo.

Prerequisiti¶

È necessario installare i seguenti prerequisiti.

macOSLinuxWindows

{{ nome_formale }} richiede Python 3.10+. È necessario anche un metodo per gestire gli ambienti virtuali (come venv).

È possibile verificare la versione di Python installata eseguendo:

$ python3 --version

Se è installata più di una versione di Python, potrebbe essere necessario sostituire python3 con un numero di versione specifico (ad esempio, python3.13).

Si consiglia di evitare le versioni di Python rilasciate di recente (cioè quelle che hanno un micro numero di versione ".0" o ".1", come ad esempio 3.14.0). Questo perché gli strumenti necessari per supportare Python su macOS spesso non sono disponibili per le versioni stabili di Python rilasciate di recente.

{{ nome_formale }} richiede Python 3.10+. È necessario anche un metodo per gestire gli ambienti virtuali (come venv).

È possibile verificare la versione di Python installata eseguendo:

$ python3 --version

Se è installata più di una versione di Python, potrebbe essere necessario sostituire python3 con un numero di versione specifico (ad esempio, python3.13).

Si consiglia di evitare le versioni di Python rilasciate di recente (cioè quelle che hanno un micro numero di versione ".0" o ".1", come ad esempio 3.14.0). Questo perché gli strumenti necessari per supportare Python su Linux spesso non sono disponibili per le versioni stabili di Python rilasciate di recente.

{{ nome_formale }} richiede Python 3.10+. È necessario anche un metodo per gestire gli ambienti virtuali (come venv).

È possibile verificare la versione di Python installata eseguendo:

C:\...>py -3 --version

Se è installata più di una versione di Python, potrebbe essere necessario sostituire la -3 con un numero di versione specifico (ad esempio, -python{{ versione_python_recente }}).

Si consiglia di evitare le versioni di Python rilasciate di recente (cioè quelle che hanno un micro numero di versione ".0" o ".1", come ad esempio 3.14.0). Questo perché gli strumenti necessari per supportare Python su Windows spesso non sono disponibili per le versioni stabili di Python rilasciate di recente.

Impostare il proprio ambiente di sviluppo¶

Il modo consigliato di impostare l'ambiente di sviluppo per {{ nome_formale }} è quello di usare un ambiente virtuale, e quindi installare la versione di sviluppo di {{ nome_formale }} e le sue dipendenze.

Clonare il repository {{ nome_formale }}¶

Quindi, andare alla pagina {{ nome_formale }} su GitHub e, se non lo si è già fatto, fare un fork del repository nel proprio account. Quindi, fare clic sul pulsante "<> Codice" sul proprio fork. Se sul computer è installata l'applicazione desktop di GitHub, si può selezionare "Apri con GitHub Desktop"; altrimenti, copiare l'URL HTTPS fornito e usarlo per clonare il repository sul computer usando la riga di comando:

macOSLinuxWindows

Eseguire il fork del repository {{ nome_formale }} e poi:

$ git clone https://github.com/<your username>/beeware.git

(sostituendo il proprio nome utente GitHub)

Eseguire il fork del repository {{ nome_formale }} e poi:

$ git clone https://github.com/<your username>/beeware.git

(sostituendo il proprio nome utente GitHub)

Eseguire il fork del repository {{ nome_formale }} e poi:

C:\...>git clone https://github.com/<your username>/beeware.git

(sostituendo il proprio nome utente GitHub)

Creare un ambiente virtuale¶

Per impostare un ambiente virtuale e aggiornare pip, eseguire:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Il prompt dovrebbe ora avere un prefisso (.venv) davanti.

Installare {{ nome_formale }}¶

Ora che si dispone del codice sorgente, si può eseguire una installazione modificabile di {{ nome_formale }} nel proprio ambiente di sviluppo. Eseguite il seguente comando:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Abilita il pre-commit¶

{{ nome_formale }} usa uno strumento chiamato pre-commit per identificare semplici problemi e standardizzare la formattazione del codice. Lo fa installando un hook git che esegue automaticamente una serie di code linters prima di finalizzare qualsiasi commit git. Per abilitare il pre-commit, eseguire:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Ora siete pronti per iniziare l'hacking su {{ nome_formale }}!

Lavora da una filiale

Prima di iniziare a lavorare sulle modifiche, assicurarsi di aver creato un ramo. Per impostazione predefinita, quando si clona il fork del repository, il check-out viene effettuato sul ramo main. Questo è una copia diretta del ramo main di {{ nome_formale }}.

Sebbene sia possibile inviare una richiesta di pull dal proprio ramo main, è preferibile non farlo. Se si invia una richiesta di pull che è quasi corretta, il membro del core team che esamina la richiesta di pull può essere in grado di apportare le modifiche necessarie, piuttosto che dare un feedback chiedendo una modifica minore. Tuttavia, se si invia la richiesta di pull dal ramo `main', ai revisori viene impedito di apportare modifiche.

Lavorare dal ramo principale rende difficile anche per lui dopo aver completato la prima richiesta di pull. Se si vuole lavorare su una seconda richiesta di pull, è necessario avere una copia "pulita" del ramo principale del progetto upstream su cui basare il secondo contributo; se si è fatto il primo contributo dal proprio ramo main, non si ha più a disposizione quella versione pulita.

Si dovrebbero invece apportare le modifiche in un ramo di funzionalità. Un ramo di funzionalità ha un nome semplice per identificare la modifica apportata. Per esempio, se si sta correggendo un bug che causa problemi di compilazione su Windows 11, si potrebbe creare un ramo di funzionalità fix-win11-build. Se il bug si riferisce a un problema specifico che è stato segnalato, è anche comune fare riferimento al numero del problema nel nome del ramo (ad esempio, fix-1234).

Per creare un ramo di funzionalità fix-win11-build, eseguire:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Evitare lo scope creep

Lo "Scope creep" si verifica quando l'elenco dei problemi risolti o delle funzionalità implementate da un singolo contributo cresce significativamente al di là di quanto previsto all'inizio del lavoro. Si inizia con un semplice problema; si scopre un problema strettamente correlato e si decide di includere anche quella soluzione; poi una terza… prima di rendersene conto, si ha una richiesta di pull che chiude 5 problemi e aggiunge 3 nuove funzionalità, comprese decine di file.

Lo Scope Creep capita a tutti. È un concetto fin troppo familiare agli sviluppatori esperti; tutti noi l'abbiamo fatto più volte e abbiamo sperimentato tutti i problemi che ne derivano.

Ci sono ragioni molto pratiche per evitare lo scope creep. Più un contributo diventa grande, più è difficile lavorarci. Diventa più difficile identificare i casi limite o i problemi potenziali, il che significa che la qualità complessiva del contributo può diminuire. Anche le revisioni diventano più impegnative quando il revisore deve occuparsi di più contesti, potenzialmente non correlati. Un contributo più grande significa più commenti di revisione e, come collaboratore, può diventare difficile seguire più thread di revisione. Anche l'esperienza su GitHub ne risentirà: l'interfaccia utente di GitHub rallenterà con l'aumentare delle dimensioni di una PR, il che significa che navigare i file attraverso l'interfaccia di GitHub e tentare di lasciare commenti di revisione diventa sempre più difficile.

Ogni volta che trovate un motivo per aggiungere al vostro contributo qualcosa che non fa esplicitamente parte della proposta originale o della segnalazione di un bug, dovete considerare se state andando incontro a un'espansione dell'ambito. Ci sono due caratteristiche distinte che potrebbero essere implementate separatamente? È possibile implementare una funzionalità con una limitazione o un bug noto, e risolvere tale bug in una richiesta di pull successiva? Una parte della correzione di un bug è indipendente da un'altra? Se una parte di un cambiamento può essere esclusa senza alterare il contributo originale, probabilmente dovrebbe esserlo.

Lo sviluppo di software è sempre un processo di miglioramento incrementale. Ogni singolo contributo dovrebbe lasciare la base di codice in uno stato migliore dopo la fusione, ma è del tutto accettabile lasciare bug o parti di funzionalità come lavoro per miglioramenti futuri. Questo può significare suddividere una richiesta di pull in più parti che possono essere riviste in modo indipendente, oppure registrare un problema in modo che qualcun altro possa indagare e risolvere il problema.

Limitare la portata di ogni contributo aiuta tutte le persone coinvolte, voi compresi. I revisori, e anche voi stessi, lo apprezzeranno.

Documentazione dell'edificio

Prima di apportare qualsiasi modifica alla documentazione di {{ nome_formale }}, è utile confermare che si può costruire la documentazione esistente.

È necessario avere un interprete Python 3.13 installato e disponibile sul proprio percorso (cioè, python3.13 deve avviare un interprete Python 3.13).

{{ nome_formale }} usa tox per costruire la documentazione. I seguenti comandi di tox devono essere eseguiti dalla stessa posizione del file tox.ini, che si trova nella directory principale del progetto.

Anteprima della documentazione in tempo reale¶

Per favorire la modifica rapida della documentazione, {{ nome_formale }} dispone di una modalità di "anteprima dal vivo".

L'anteprima live verrà generata con avvisi!

Il servizio live è disponibile per iterare gli aggiornamenti della documentazione. Mentre si aggiornano le cose, si può introdurre un problema di markup. I problemi considerati un `AVVERTIMENTO' causano il fallimento della compilazione standard; tuttavia, il servizio live è impostato per indicare gli avvertimenti nell'output della console, pur continuando la compilazione. Questo permette di iterare senza dover riavviare l'anteprima live.

Un AVVISO' è diverso da unERRORE'. Se si introduce un problema considerato un ERRORE, il servizio live fallirà e richiederà un riavvio. Non si riavvierà fino a quando il problema WARNING non sarà risolto.

Per avviare il server live:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Questo costruisce la documentazione, avvia un server web per servire la documentazione e controlla il file system per qualsiasi modifica alla fonte della documentazione.

Una volta avviato il server, nell'output della console si vedrà qualcosa di simile a quanto segue:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Aprire un browser e navigare all'URL fornito. Ora si può iniziare a iterare sulla documentazione. Se viene rilevata una modifica, la documentazione viene ricostruita e qualsiasi browser che visualizza la pagina modificata viene automaticamente aggiornato.

docs-live è un passo iniziale

L'esecuzione di docs-live per lavorare con il server live è pensata per l'iterazione iniziale. Si dovrebbe sempre eseguire una build locale prima di inviare una richiesta di pull.

Costruzione locale¶

Una volta terminata l'iterazione, è necessario eseguire una compilazione locale della documentazione. Questo processo di creazione è progettato per fallire se ci sono problemi di markup. In questo modo è possibile individuare tutto ciò che potrebbe essere sfuggito con il server live.

Generazione di una build locale¶

Per generare una build locale:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

L'output di questa compilazione sarà nella cartella _build nella radice del progetto.

Generazione di una build locale tradotta¶

La documentazione di BeeWare è tradotta in più lingue. Gli aggiornamenti della documentazione in inglese possono potenzialmente causare problemi nelle build delle altre lingue. È importante verificare che tutte le build funzionino prima di inviare una richiesta di pull.

Per generare una build di tutte le traduzioni disponibili:

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

L'output di ogni compilazione di una lingua si trova nella directory associata _build/html/<languagecode>, dove <languagecode> è il codice di due o cinque caratteri associato alla lingua specifica (ad esempio, fr per il francese, it per l'italiano, ecc.)

Se si riscontra un problema con una singola compilazione, è possibile eseguire quella singola compilazione separatamente eseguendo tox -e docs-<languagecode>. Per esempio, per creare solo la documentazione francese, eseguire:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

L'output di una compilazione in una sola lingua si trova nella directory _build.

Linting della documentazione¶

Il processo di compilazione identifica i problemi di Markdown, ma {{ nome_formale }} esegue alcuni controlli aggiuntivi per lo stile e la formattazione, noti come "linting". Per eseguire i controlli di lint:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

In questo modo si convalida che la documentazione non contiene:

collegamenti ipertestuali morti
parole sbagliate

Se un'ortografia valida di una parola viene identificata come errata, aggiungere la parola all'elenco in docs/spelling_wordlist. Questo aggiungerà la parola al dizionario del correttore ortografico. Quando si aggiunge a questo elenco, ricordate:

Preferiamo l'ortografia statunitense, con alcune libertà per i colloqui specifici della programmazione (ad esempio, "apps") e per i verbi dei nomi (ad esempio, "scrollable").
Qualsiasi riferimento al nome di un prodotto deve utilizzare la capitalizzazione preferita dal prodotto stesso. (ad esempio, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Se un termine viene usato "come codice", allora dovrebbe essere citato come letterale (come questo) invece di essere aggiunto al dizionario.

Scrittura della documentazione

Questi sono i passi da seguire per scrivere il contributo alla documentazione di {{ nome_formale }}.

Aggiornamento della documentazione esistente¶

Se si sta modificando la documentazione esistente, è necessario individuare il file nella cartella /docs/en. La struttura del file segue quella della pagina, quindi è possibile individuare il file utilizzando l'URL della documentazione.

Aggiunta di nuova documentazione¶

Se si sta aggiungendo un nuovo documento, ci sono alcuni passaggi in più.

È necessario creare il documento nella posizione appropriata all'interno della cartella docs/en. A titolo di esempio, diciamo che stiamo aggiungendo un nuovo documento con il nome di file new_doc.md.

Quindi, è necessario aggiornare il file docs/en/SUMMARY.md per includere il nuovo file. Il file SUMMARY.md è organizzato in modo da riflettere la struttura della cartella docs/en, ma soprattutto determina direttamente la struttura della barra laterale sinistra. Se si individua la sezione in cui si intende includere new_doc.md, non è necessario modificare nulla in SUMMARY.md se si vede un percorso jolly. Ad esempio:

- ./path/to/directory/*

Se la sezione in cui si intende includere new_doc.md è un elenco di singoli collegamenti a Markdown, è necessario aggiungere un collegamento esplicito al proprio. Per esempio:

- [My new document](new_doc.md)

Scrivere la documentazione¶

A questo punto è possibile aprire il file desiderato nel proprio editor e iniziare a scrivere.

Abbiamo una guida allo stile della documentazione che delinea le nostre linee guida per la scrittura della documentazione di BeeWare.

Aggiungi una nota di modifica

Molti strumenti di BeeWare usano towncrier per aiutare a costruire le note di rilascio per ogni release. Quando si invia una richiesta di pull a uno degli strumenti applicabili, questa dovrà includere una nota di modifica; questa nota di modifica diventerà la voce nelle note di rilascio che descriverà la modifica apportata.

Ogni richiesta di pull deve includere almeno un file nella cartella changes/ che fornisca una breve descrizione della modifica implementata dalla richiesta di pull. La nota di modifica deve essere in formato Markdown, in un file dal nome <id>.<tipo di frammento>.md. Se la modifica proposta risolve un bug o implementa una funzionalità per la quale esiste un numero di problema esistente, l'ID sarà il numero di quel ticket. Se la modifica non ha un problema corrispondente, il numero di PR può essere usato come ID. Non si conosce il numero di PR finché non si invia la richiesta di pull, quindi il primo passaggio di CI non supererà il controllo towncrier; aggiungendo la nota di modifica e inviando un aggiornamento della PR, il CI dovrebbe passare.

Esistono cinque tipi di frammenti:

caratteristica: La PR aggiunge un nuovo comportamento o una capacità che non era possibile in precedenza (ad esempio, l'aggiunta del supporto per un nuovo formato di pacchettizzazione o una nuova funzionalità in un formato di pacchettizzazione esistente);
bugfix: La PR corregge un bug nell'implementazione esistente;
doc: Il PR rappresenta un miglioramento significativo della documentazione;
La PR rappresenta una modifica incompatibile con le versioni precedenti dell'API {{ nome_formale }}. API; oppure
misc; Una modifica minore o amministrativa (ad esempio, la correzione di un errore di battitura, un chiarimento linguistico minore o l'aggiornamento della versione di una dipendenza) che non deve essere annunciata nelle note di rilascio.

Questa descrizione nella nota di modifica dovrebbe essere un riassunto di alto livello "marketing" della modifica dal punto di vista dell'utente, non una descrizione tecnica approfondita o un dettaglio di implementazione. Si distingue da un messaggio di commit: un messaggio di commit descrive ciò che è stato fatto in modo che i futuri sviluppatori possano seguire il ragionamento per una modifica; la nota di modifica è una descrizione a beneficio degli utenti, che potrebbero non avere conoscenze interne.

Ad esempio, se si risolve un bug relativo alla denominazione del progetto, il messaggio di commit potrebbe essere il seguente:

Applicare un controllo di espressione regolare più forte per escludere i nomi di progetto che iniziano con cifre.

La nota di modifica corrispondente sarebbe qualcosa di simile:

I nomi dei progetti non possono più iniziare con un numero.

Alcune PR introducono più funzionalità e correggono più bug, oppure introducono più modifiche incompatibili con il passato. In questo caso, la PR può avere più file di note di modifica. Se è necessario associare due tipi di frammenti allo stesso ID, è possibile aggiungere un suffisso numerico. Ad esempio, se la PR 789 ha aggiunto una funzionalità descritta dal ticket 123, ha chiuso un bug descritto dal ticket 234 e ha apportato due modifiche incompatibili, si potrebbero avere 4 file di note di modifica:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

Per maggiori informazioni su towncrier e sui tipi di frammenti, vedere News Fragments. È anche possibile vedere esempi esistenti di frammenti di notizie nella cartella changes del repository {{ nome_formale }}. Se questa cartella è vuota, è probabile che sia perché {{ nome_formale }} ha recentemente pubblicato un nuovo rilascio; i file delle note di modifica vengono cancellati e combinati per aggiornare le note di rilascio a ogni rilascio. Si può guardare a quel file per vedere lo stile di commento richiesto; si può guardare a recent merged PRs per vedere come formattare le note di modifica.

Invia una richiesta pull

Dopo aver effettuato il commit di tutte le modifiche, si è pronti a inviare una richiesta di pull. Per garantire un processo di revisione senza intoppi, ci sono alcuni passi da fare.

Lavorare con il pre-commit¶

Quando si esegue il commit di una modifica, il pre-commit viene eseguito automaticamente. Se vengono riscontrati problemi con il commit, questo causerà l'insuccesso del commit. Dove possibile, pre-commit apporterà le modifiche necessarie per correggere i problemi riscontrati. Nell'esempio seguente, il controllo ruff ha rilevato un problema di formattazione del codice:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

In questo caso, ruff ha risolto automaticamente il problema; è quindi possibile reinserire tutti i file che sono stati modificati come risultato dei controlli pre-commit e reinserire la modifica. Tuttavia, alcuni controlli richiedono modifiche manuali. Una volta apportate le modifiche, si possono aggiungere nuovamente i file modificati e rifare il commit.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Una volta che tutto è stato superato, si vedrà un messaggio che indica che il commit è stato finalizzato e il log di git mostrerà il commit come l'aggiunta più recente. Ora si è pronti a fare il push su GitHub.

Spingere le modifiche su GitHub e creare la richiesta di pull.¶

La prima volta che si effettua un push su GitHub, viene fornito un URL che porta direttamente alla pagina di GitHub per creare una nuova richiesta di pull. Seguire l'URL e creare la richiesta di pull.

Di seguito viene mostrato un esempio di cosa aspettarsi da push, con l'URL evidenziato.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Se avete precedentemente spinto il ramo corrente su GitHub, non riceverete più l'URL. Tuttavia, ci sono altri modi per raggiungere l'URL di creazione della PR:

Navigare nel repository upstream, cliccare su "Pull Requests" e poi su "New pull request" e scegliere il repository da cui si vuole inviare la richiesta di pull.
Se si è effettuato un push di recente, navigare nel repository upstream, individuare il banner sopra l'elenco dei file che indica che il repository ha "avuto push recenti" e fare clic sul pulsante "Compare & pull request".
Utilizzare il comando gh pr create di GitHub CLI e compilare le richieste.
Usare il comando GitHub CLI gh pr create --web per aprire un browser web alla pagina di creazione della PR.

Ognuna di queste opzioni consente di creare una nuova richiesta di pull.

La CLI GitHub: gh

GitHub fornisce la GitHub CLI, che consente di accedere a molte delle funzionalità di GitHub dal proprio terminale, attraverso il comando gh. La Documentazione della GitHub CLI copre tutte le funzionalità.

Contenuto della richiesta di pull¶

Il titolo di una richiesta di pull deve essere informativo, chiaro e conciso. Cercate di mantenerlo breve se possibile, ma titoli più lunghi sono accettabili, se necessario. Un buon titolo di una PR dovrebbe dare a una persona senza alcun contesto un'idea ragionevolmente solida di quale sia il bug o la funzionalità implementata dalla PR.

La descrizione della PR deve riflettere chiaramente le modifiche apportate. Una persona priva di contesto dovrebbe essere in grado di leggere la descrizione e comprendere in modo relativamente completo il motivo della modifica. Evitate battute, espressioni idiomatiche, colloquialismi e formattazioni inutili, come l'uso di tutte le maiuscole o di una punteggiatura eccessiva; si tratta di una spiegazione diretta di ciò che sta accadendo nella vostra RP, ed evitare questi elementi rende la descrizione più accessibile agli altri.

Se ci sono casi di riproduzione o regimi di test utilizzati che non fanno già parte delle modifiche presenti nella PR, devono essere spiegati e inclusi nella PR. La spiegazione dovrebbe includere come eseguirli e cosa fare per riprodurre il risultato desiderato.

Se la richiesta di pull risolve il problema #1234, si dovrebbe includere il testo Fixes #1234 nella descrizione della richiesta di pull. Questo farà sì che il problema venga automaticamente chiuso quando la richiesta di pull viene unita. È possibile fare riferimento ad altre discussioni, problemi o richieste di pull usando la stessa sintassi #1234. È possibile fare riferimento a un problema su un repository diverso anteponendo il numero - per esempio python/cpython#1234 si riferisce al problema 1234 sul repository CPython.

Integrazione continua¶

L'integrazione continua, o CI, è il processo di esecuzione di controlli automatici sulla richiesta di pull. Questo può includere controlli semplici, come la verifica che il codice sia formattato correttamente, ma anche l'esecuzione della suite di test e la creazione della documentazione.

Le modifiche che possono causare un fallimento del CI sono molteplici. In linea di massima, non revisioneremo una PR che non passa il CI. Se si crea una richiesta di pull e il CI fallisce, non inizieremo la revisione finché non passerà. Se le vostre modifiche causano un fallimento, è vostra responsabilità indagare sul motivo e risolvere il problema.

Quando il CI fallisce, i link di fallimento vengono visualizzati in fondo alla pagina PR, sotto il titolo "Alcuni controlli non hanno avuto successo". Verrà visualizzato un elenco di controlli falliti, che apparirà in cima all'elenco di tutti i controlli se ci sono anche controlli superati. Se si fa clic sul link relativo al fallimento, si accede al registro. Il log spesso fornisce tutte le informazioni necessarie per capire cosa ha causato il fallimento. Leggete il registro e cercate di capire perché si è verificato il guasto, quindi fate il necessario per risolverlo.

Occasionalmente, un controllo CI fallisce per motivi non correlati alle modifiche apportate. Ciò potrebbe essere dovuto a un problema sulla macchina che esegue il controllo CI o perché un controllo CI è instabile. Se si verifica un errore e si è abbastanza certi che non sia correlato alle modifiche, aggiungere un commento alla PR e lo esamineremo.

Per attivare un nuovo ciclo CI, è necessario apportare nuove modifiche al ramo.

Se vi trovate in una situazione in cui avete bisogno di aiuto per far passare l'IC, lasciate un commento sulla PR e fateci sapere che faremo il possibile per aiutarvi.

I controlli pre-commit e `towncrier

Se uno dei due controlli pre-commit o towncrier fallisce, la maggior parte degli altri controlli del CI saranno bloccati. È necessario risolvere i problemi applicabili prima che l'intero set di controlli venga eseguito.

Le risorse del CI sono limitate. È importante capire che ogni volta che si esegue il push sul ramo, si avvia il CI. Se si devono apportare diverse modifiche, è meglio farle localmente e spingerle tutte in una volta. CI verrà eseguito solo sul commit più recente in un batch, riducendo al minimo il carico sul nostro sistema CI.

Il processo di invio della PR non è concluso finché non passa il CI, o non si può fornire una spiegazione del perché non lo sia.