Esaminare e inviare una richiesta pull
La richiesta pull consente di ottenere informazioni sulla piattaforma Learn. È stata creata una richiesta pull, ma non è ancora stata inviata alla coda delle richieste pull del repository di destinazione. Come per molti progetti open source, è disponibile una serie di controlli e revisioni da eseguire per convalidare le modifiche prima della pubblicazione.
Anatomia di una richiesta pull
Una richiesta pull mostra l'utente GitHub che ha creato la richiesta pull, il repository di destinazione e il ramo in cui è stata creata tale richiesta. Le richieste pull contengono diverse schede nella parte superiore, tra cui:
- Scheda Conversazione: un dashboard in cui è possibile visualizzare e rispondere ai commenti di altri collaboratori, visualizzare un elenco di notifiche durante il processo di compilazione e revisione e utilizzare l'automazione dei commenti per eseguire le azioni.
- Scheda Commit: un record delle modifiche apportate a tale ramo.
- Scheda File modificati: un confronto tra i file modificati nella richiesta pull con lo stato precedente.
Prestare attenzione alla scheda Conversazione, in cui vengono visualizzati gli aggiornamenti o le notifiche e le discussioni tra l'utente, i revisori e altri collaboratori. In questa sede, è anche possibile aggiungere commenti hashtag per eseguire azioni, ad esempio l'approvazione della richiesta pull per indicare che è pronta per essere convalidata e unita oppure bloccarla, se è necessario sospendere il processo.
Le richieste pull sono spesso dotate di etichette associate per indicare il relativo stato, ad esempio draft per specificare le richieste pull in stato di bozza che non sono pronte per la revisione o do-not-merge per le richieste pull nuove o non revisionate.
Convalida
Prima di poter eseguire l'unione della richiesta pull nel ramo di destinazione, potrebbe essere necessario passare uno o più processi di convalida della richiesta pull. Dopo la selezione di Crea richiesta pull, GitHub esegue le convalide configurate per il repository. Al termine del processo di convalida, i risultati vengono visualizzati nella richiesta pull.
I processi di convalida variano a seconda dell'ambito delle modifiche proposte e delle regole del repository di destinazione. Dopo aver inviato la richiesta pull, è possibile prevedere che si verifichino una o più delle operazioni seguenti:
- Unione: un test di unione di GitHub di base si verifica prima di tutto per verificare se le modifiche proposte nel ramo sono in conflitto con il ramo di destinazione. Se la richiesta pull indica che il test non è riuscito, è necessario riconciliare il contenuto che causa il conflitto di unione, prima che l'elaborazione possa continuare.
- Contratto di licenza per contributi (CLA): se si contribuisce a un repository pubblico e non si è un dipendente Microsoft, a seconda dell'entità delle modifiche proposte, la prima volta che si invia una richiesta pull a tale repository potrebbe essere richiesto di completare un breve contratto di licenza. Dopo aver superato il passaggio del contratto di licenza, la richiesta pull verrà elaborata.
- Etichettatura: le etichette vengono applicate automaticamente alla richiesta pull per indicare lo stato della richiesta mentre attraversa il flusso di lavoro di convalida. Ad esempio, è possibile che alle nuove richieste pull venga automaticamente associata l'etichetta
do-not-merge, a indicare che la richiesta pull non ha ancora completato la convalida, la revisione e i passaggi di approvazione. - Convalida e compilazione: una serie di controlli automatici verificano se le modifiche superano i test di convalida. I test di convalida potrebbero generare avvisi o errori, richiedendo di apportare modifiche a uno o più file nella richiesta pull, prima di poter procedere con l'unione. I risultati del test di convalida vengono aggiunti come commento nella richiesta pull per la revisione da parte dell'utente e potrebbero essere inviati a quest'ultimo 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 potrebbe essere unita automaticamente, se supera i test di convalida e determinati criteri. In questo caso, non è necessario eseguire altre operazioni.
Revisione e approvazione
Ci siamo quasi. Al termine dell'elaborazione delle richieste pull, è consigliabile esaminare i risultati (ad esempio, commenti pull, URL di anteprima) per determinare se sono necessarie ulteriori modifiche prima di approvare l'unione. Se un revisore della richiesta pull l'ha esaminata, può anche fornire commenti tramite commenti in caso di problemi o domande in sospeso che impediscono l'unione.
Usare l'automazione dei commenti per eseguire azioni importanti nella richiesta pull. L'automazione dei commenti consente agli utenti di assegnare l'etichetta appropriata alla richiesta pull per aggiornarne lo stato o classificarla. Se si lavora in un repository in cui è stata implementata l'automazione dei commenti, usare i commenti hashtag per assegnare o modificare le etichette, chiudere una richiesta pull o sospendere l'unione. Ad esempio, dopo aver apportato modifiche, digitare il commento #sign-off per modificare l'etichetta della richiesta pull da do-not-merge a ready-for-review.
Usare i commenti nella tabella seguente per eseguire azioni chiave nella richiesta pull:
| Commento hashtag | Risultato |
|---|---|
#sign-off |
Assegna automaticamente l'etichetta ready-to-merge per informare i revisori nel repository che la richiesta pull è pronta per la revisione/unione. Se non si è l'autore elencato e si tenta di disconnettersi da una richiesta pull pubblica usando il commento #sign-off, la richiesta pull viene aggiornata per indicare che solo l'autore può assegnare l'etichetta. |
#hold-off |
Rimuove l'etichetta ready-to-merge nel caso in cui si cambi idea o si commetta un errore. |
#please-close |
Chiude la richiesta pull se si decide di non unire le modifiche. |
#please-open |
Riapre una richiesta pull o un problema chiuso. |
È necessario immettere il commento #sign-off per unire le modifiche. Anche se tutte le revisioni e i controlli di convalida vengono superati, si è responsabili dell'utilizzo di questo commento per indicare ai revisori delle richieste pull e agli amministratori del repository che le modifiche sono pronte per l'unione da parte dell'utente. Quando i revisori determinano che la richiesta pull è senza problemi ed è stata approvata, le modifiche vengono unite nuovamente nel ramo padre e la richiesta pull viene chiusa.
Pubblicazione
Tenere presente che la richiesta pull deve essere unita da un revisore della richiesta pull, prima che le modifiche possano essere incluse nella successiva esecuzione della pubblicazione pianificata. In genere, le richieste pull vengono esaminate e unite in ordine di invio.
Dopo l'approvazione e l'unione dei contributi, il processo di pubblicazione ne effettua il prelievo. A seconda del team che gestisce il repository a cui si contribuisce, i tempi di pubblicazione possono variare, ma in genere si verificano almeno una volta ogni giorno feriale. Per la visualizzazione online degli articoli dopo la pubblicazione possono essere richiesti fino a 45 minuti.
Una volta pubblicate le modifiche, saranno live su Microsoft Learn per consentire ad altri utenti di trarne insegnamento.
Scenario: Pubblicare le modifiche nel servizio app di Azure
Sulla base dell'esperienza precedente, è stata individuata l'opportunità di aggiungere alcune informazioni utili a una pagina della documentazione del servizio app e di creare una richiesta pull per aggiungere le modifiche. È ora possibile esaminare e approvare la richiesta pull per pubblicare le modifiche effettuate.