Flusso di lavoro per i contributi a GitHub per le modifiche di rilievo o di lunga durata

Importante

Tutti i repository che pubblicano in Microsoft Learn hanno adottato il codice di condotta Microsoft Open Source o il codice di comportamento di .NET Foundation. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com o conduct@dotnetfoundation.org per eventuali domande o commenti.

Le correzioni o i chiarimenti secondari alla documentazione e agli esempi di codice nei repository pubblici sono coperti dalle condizioni per l'utilizzo learn.microsoft.com. Per le novità o le modifiche significative verrà generato un commento nella richiesta pull con la richiesta di inviare un contratto di licenza online per i contributi (Contribution License Agreement, CLA) se non si è dipendenti Microsoft. Sarà necessario compilare il modulo online, prima che la richiesta pull possa essere unita.

Panoramica

Questo flusso di lavoro è appropriato per gli autori di contributi che devono apportare modifiche di rilievo o che forniscono contributi di frequente per un repository. I collaboratori frequenti propongono in genere modifiche continuative (di lunga durata) sottoposte a vari cicli di compilazione, convalida e gestione temporanea oppure con un'elaborazione che richiede più giorni prima dell'approvazione e unione della richiesta pull.

Alcuni esempi di questo tipo di contributi includono:

  • Proposta di contributi estesi. Ad esempio è possibile che l'utente crei contributi (aggiunte/modifiche/eliminazioni) estesi su più articoli, che devono essere sottoposti a commit/test come singola unità di lavoro in una singola richiesta pull.
  • Creazione e pubblicazione di un nuovo articolo, per cui è in genere necessario un editor locale più avanzato.
  • Aggiunta di nuove immagini o aggiornamento di immagini, operazioni che richiedono in genere la creazione simultanea di una nuova sottodirectory media, file immagine, aggiornamenti dei collegamenti alle immagini negli articoli e visualizzazione in anteprima dei file markdown in un editor locale per testare il rendering delle immagini.
  • Aggiornamento di un articolo per un periodo di giorni prima della pubblicazione. In questi casi, in genere è necessario eseguire l'integrazione regolare di altre modifiche che si verificano nel ramo predefinito. Questa integrazione risulta più semplice tramite Git Bash e la modifica in locale. Se questo tipo di operazione viene eseguita con l'interfaccia utente di GitHub, senza eseguire immediatamente il commit delle modifiche, si corre anche il rischio di perderle.
  • Aggiornamenti continui dello stesso articolo dopo l'apertura di una richiesta pull (a meno che non si abbia familiarità con l'esecuzione di questa operazione tramite l'interfaccia utente di GitHub). L'uso dell'interfaccia utente di GitHub potrebbe portare alla creazione di più richieste pull in sospeso per lo stesso file, potenzialmente in conflitto.

Terminologia

Prima di iniziare, è opportuno rivedere alcuni dei termini di Git/GitHub usati in questo flusso di lavoro. Non è importante comprenderli appieno in questa fase. Basta ricordarsi che verranno illustrati in maggiore dettaglio e che è possibile fare riferimento a questa sezione nel caso occorra verificare una definizione.

Nome Descrizione
fork Normalmente usato come sostantivo per fare riferimento a una copia di un repository principale di GitHub. In pratica, un fork è semplicemente un altro repository, ma è speciale perché GitHub mantiene un collegamento con il repository principale/padre. A volte, questo termine descrive un'operazione, ad esempio in "è necessario prima di tutto creare un fork del repository.".
remoto Connessione denominata a un repository remoto, ad esempio il remoto "origin" o "upstream". Git la indica come remota perché è usata per fare riferimento a un repository ospitato in un altro computer. In questo flusso di lavoro, un remoto è sempre un repository di GitHub.
origin Nome assegnato alla connessione tra il repository locale e il repository da cui è stato clonato. In questo flusso di lavoro, origin indica la connessione al fork. Questo termine viene a volte usato per fare riferimento in modo abbreviato al repository origin, come in "Ricordarsi di eseguire il push delle modifiche nell'origine."
upstream Come nel caso del remoto origin, upstream è una connessione denominata a un altro repository. In questo flusso di lavoro, upstream rappresenta la connessione tra il repository locale e il repository principale, da cui è stato creato il fork. Questo termine viene a volte usato per fare riferimento in modo abbreviato al repository upstream, come in "Ricordarsi di effettuare il pull delle modifiche dall'upstream".

Flusso di lavoro

Importante

Se non è già stato fatto, è necessario completare i passaggi della sezione di configurazione. Questa sezione descrive come configurare l'account GitHub, installare Git Bash e il Markdown editor, creare un fork e configurare il repository locale. Se non si ha familiarità con i concetti principali di Git e GitHub, come repository o ramo, leggere prima di tutto Concetti fondamentali di Git e GitHub.

In questo flusso di lavoro, le modifiche seguono un ciclo ripetitivo. A partire dal repository locale nel dispositivo dell'utente, il flusso torna verso il fork di GitHub, poi nel repository principale di GitHub, quindi di nuovo in locale quando si incorporano le modifiche di altri collaboratori.

Usare il flusso GitHub

Tenere presente i concetti fondamentali di Git e GitHub che un repository Git contiene un ramo predefinito, oltre a eventuali rami aggiuntivi in corso che non sono stati integrati nel ramo predefinito. Ogni volta che si introduce un set di modifiche correlate dal punto di vista logico, è buona norma creare un ramo di lavoro per gestire le modifiche in tutte le fasi del flusso di lavoro. In questo caso viene fatto riferimento come ramo di lavoro perché si tratta di un'area di lavoro per eseguire l'iterazione/perfezionare le modifiche, fino a quando non possono essere integrate nel ramo predefinito.

La possibilità di isolare modifiche correlate in un ramo specifico consente di controllare e introdurre tali modifiche in modo indipendente, destinandole a una fase di rilascio specifica nel ciclo di pubblicazione. In contesti reali, a seconda del tipo di lavoro svolto, è facile ritrovarsi con vari rami di lavoro nel repository a lavorare su più rami contemporaneamente, ognuno dei quali rappresenta un progetto diverso.

Suggerimento

Apportare le modifiche nel ramo predefinito non è una procedura consigliata. Si supponga di usare il ramo predefinito per introdurre un set di modifiche per una versione di funzionalità programmata. Dopo aver completato le modifiche si aspetta il momento previsto per il rilascio. Nel frattempo, si ha quindi una richiesta urgente di correzione di un elemento, in modo da apportare la modifica a un file nel ramo predefinito e quindi pubblicare la modifica. In questo esempio, vengono pubblicate inavvertitamente sia la correzione che le modifiche che erano in attesa della data specifica di rilascio.

Di seguito viene descritta la procedura per creare un nuovo ramo di lavoro nel repository locale, per raccogliere le modifiche proposte. Se è stato configurato Git Bash (vedere Installare gli strumenti di creazione del contenuto), è possibile creare un nuovo ramo ed eseguire il "checkout" del ramo con un unico comando dall'interno del repository clonato:

git checkout -b "branchname"

Poiché ogni client Git presenta differenze, consultare la documentazione relativa al client in uso. È possibile visualizzare una panoramica del processo relativo al flusso GitHub nella Guida di GitHub.

Apportare le modifiche

Ora che è disponibile una copia ("clone") del repository Microsoft e che è stato creato un ramo, è possibile apportare tutte le modifiche che si ritiene possano essere utili per la community usando qualsiasi editor di testo o Markdown, come descritto nella pagina Installare gli strumenti di creazione del contenuto. È possibile salvare le modifiche localmente senza che sia necessario inviarle a Microsoft fino a quando non si è pronti.

Salvataggio delle modifiche nel repository

Prima di inviare le modifiche all'autore, è necessario salvarle nel repository GitHub. Anche se tutti gli strumenti sono diversi, anche in questo caso è possibile eseguire l'operazione con pochi passaggi usando la riga di comando di Git Bash.

Prima di tutto, dall'interno del repository è necessario preparare tutte le modifiche in preparazione del commit successivo. Questa operazione può essere eseguita con il comando seguente:

git add --all

Successivamente, è necessario eseguire il commit delle modifiche salvate nel repository locale. Questa operazione può essere eseguita in Git Bash con il comando seguente:

git commit -m "Short Description of Changes Made"

Infine, dato che il ramo è stato creato nel computer locale, è necessario fare in modo che il fork nell'account GitHub.com ne sia a conoscenza. Se si usa Git Bash, è possibile eseguire questa operazione con il comando seguente:

git push --set-upstream origin <branchname>

Il processo è completo. Il codice è ora disponibile nel repository GitHub e pronto per la creazione di una richiesta pull.

Suggerimento

Anche se le modifiche diventano visibili nell'account GitHub personale quando si effettua il push, non è obbligatorio inviare immediatamente una richiesta pull. Se si vuole interrompere il lavoro e tornare in un secondo momento per mettere a punto altri dettagli, è possibile farlo.

Se è necessario apportare una correzione nel materiale inviato, non è un problema. È sufficiente apportare le modifiche nello stesso ramo e quindi eseguire di nuovo il commit e il push (non è necessario impostare il server upstream nei push successivi dello stesso ramo).

Altre modifiche

Se risulta necessario apportare altre modifiche non correlate a queste Tornare al ramo predefinito, eseguire il pull dal repository upstream per assicurarsi che il fork sia aggiornato ed estrarre un nuovo ramo. Eseguire i comandi seguenti in Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"

Nota

I comandi precedenti presuppongono che il repository usato abbia main come ramo predefinito. Se il primo comando ha esito negativo, è probabile che il ramo predefinito non sia stato rinominato. Sostituire main nei primi due comandi con master per verificarlo.

Si è tornati in un nuovo ramo e si è in grado di essere un esperto che contribuisce.

Elaborazione delle richieste pull

Nella sezione precedente è stato illustrato il processo di invio delle modifiche proposte raggruppandole in una nuova richiesta pull che viene quindi aggiunta alla coda delle richieste pull del repository di destinazione. Una richiesta pull attiva il modello per la collaborazione di GitHub, richiedendo il pull delle modifiche dal ramo di lavoro e la loro unione in un altro ramo. Nella maggior parte dei casi, tale ramo è il ramo predefinito nel repository principale.

Convalida

Prima di poter essere unita al ramo di destinazione, la richiesta pull potrebbe dover superare uno o più processi di convalida. I processi possono variare a seconda della portata delle modifiche proposte e delle regole del repository di destinazione. I passaggi successivi all'invio di una richiesta pull possono essere i seguenti:

  • Mergeability: si verifica prima un test di mergeability di GitHub di base per verificare se le modifiche proposte nel ramo non sono in conflitto con il ramo di destinazione. Se il test ha esito negativo per la richiesta pull, prima di poter continuare l'elaborazione è necessario riconciliare il contenuto che causa i conflitti di unione.
  • Contratto di licenza per contributi: se si inviano contributi a un repository pubblico e non si è un dipendente Microsoft, a seconda della portata delle modifiche proposte potrebbe essere richiesto di completare un breve contratto di licenza per contributi in occasione del primo invio di una richiesta pull al repository in questione. Una volta inoltrato il contratto, la richiesta pull viene elaborata.
  • Etichettatura: alla richiesta pull vengono applicate automaticamente etichette, usate per indicarne lo stato durante i vari passaggi del flusso di lavoro di convalida. Ad esempio alle nuove richieste pull può essere assegnata automaticamente l'etichetta "do-not-merge", a indicare che per la richiesta devono ancora essere completati i passaggi di convalida, revisione e approvazione.
  • Convalida e compilazione: una serie di controlli automatici verificano se le modifiche superano i test di convalida. I test di convalida possono restituire avvisi o errori, rendendo necessaria la modifica di uno o più file nella richiesta pull prima di poter procedere con l'unione. I risultati dei test di convalida vengono aggiunti come commenti nella richiesta pull per consentire la consultazione e possono essere inviati all'autore tramite posta elettronica.
  • Gestione temporanea: dopo il completamento corretto della convalida e della compilazione, le pagine di articoli interessate dalle modifiche vengono distribuite automaticamente in un ambiente di gestione temporanea per la revisione. Gli URL di anteprima appaiono in un commento della richiesta pull.
  • Unione automatica: la richiesta pull può essere unita automaticamente se supera i test di convalida e soddisfa determinati criteri. In tal caso non è necessario eseguire altre operazioni.

Revisione e approvazione

Dopo il completamento di tutti i passaggi di elaborazione della richiesta pull, è necessario rivedere i risultati (commenti, URL di anteprima e così via) per stabilire se sono necessarie ulteriori modifiche ai file prima dell'approvazione per l'unione. Se la richiesta pull è stata verificata da un revisore di richieste pull, il revisore può aggiungere commenti se rileva domande/problemi in sospeso da risolvere prima dell'unione.

L'automazione dei commenti consente agli utenti con autorizzazioni di lettura, ovvero quelli senza autorizzazioni di scrittura in un repository, di eseguire un'azione di scrittura tramite l'assegnazione dell'etichetta appropriata a una richiesta pull. Se si sta lavorando in un repository in cui è stata abilitata l'automazione dei commenti, usare i commenti hashtag elencati nella tabella seguente per assegnare e modificare etichette o chiudere una richiesta pull. Ogni volta che vengono proposte modifiche ai propri articoli, i dipendenti Microsoft riceveranno inoltre notifiche tramite posta elettronica per la revisione e l'approvazione delle richieste pull del repository pubblico.

Commento hashtag Funzione Disponibilità repository
#sign-off Quando l'autore di un articolo digita il commento #sign-off nel flusso di commenti, viene assegnata l'etichetta ready-to-merge. Questa etichetta consente ai revisori nel repository di sapere quando una richiesta pull è pronta per la revisione/unione.

Se un collaboratore che non è l'autore indicato tenta di approvare una richiesta pull di un repository pubblico usando il commento #sign-off, nella richiesta pull viene scritto un messaggio indicante che solo l'autore è autorizzato ad assegnare l'etichetta.
Public and private
#hold-off Se l'autore cambia idea o commette un errore, può digitare #hold-off nel commento di una richiesta pull per rimuovere l'etichetta ready-to-merge. Nel repository privato viene assegnata l'etichetta do-not-merge. Public and private
#please-close Se l'autore decide di non unire le modifiche, può digitare #please-close nel flusso dei commenti per chiudere la richiesta pull. Pubblico

Quando la richiesta pull è corretta e approvata le modifiche vengono unite nel ramo padre e la richiesta viene chiusa.

Pubblicazione

Ricordare che la richiesta pull deve essere unita da un revisore di richieste pull prima che le modifiche possano essere incluse nella successiva operazione di pubblicazione pianificata. Le richieste pull vengono in genere riviste/unite nell'ordine di invio. Se la richiesta pull deve essere unita per una scadenza di pubblicazione specifica è consigliabile collaborare con il revisore della richiesta pull con il dovuto anticipo, per assicurarsi che l'unione avvenga prima della pubblicazione.

Dopo aver approvato e unito i contributi, il processo di pubblicazione li raccoglie. I tempi di pubblicazione possono variare a seconda del team che gestisce il repository di destinazione dei contributi. Gli articoli pubblicati nelle posizioni seguenti vengono normalmente distribuiti alle 10:30 e alle 3:30 Ora Pacifico, lunedì-venerdì:

Per la visualizzazione online degli articoli dopo la pubblicazione possono essere richiesti fino a 45 minuti. Dopo la pubblicazione dell'articolo è possibile verificare che le modifiche siano disponibili nell'URL appropriato: https://learn.microsoft.com/<path-to-your-article-without-the-md-extension>.

Passaggi successivi

L'operazione è terminata. Hai contribuito al contenuto di Microsoft Learn!