Apportare modifiche importanti alla documentazione di Microsoft Learn

Articolo
02/01/2024

Importante

Tutti i repository che pubblicano in Microsoft Learn hanno adottato il codice di comportamento Microsoft Open Source o il codice di comportamento di .NET Foundation. Per altre informazioni, vedere le domande frequenti sul Codice di comportamento. 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 video2.skills-academy.com. Eventuali modifiche genereranno un commento nella richiesta pull, chiedendo di inviare un contratto di licenza per contributi online (CLA) se non si è un dipendente di Microsoft. Sarà necessario compilare il modulo online, prima che la richiesta pull possa essere unita.

Questo articolo illustra come modificare un articolo di Microsoft Learn usando gli strumenti locali ed è adatto per un collaboratore che deve apportare una modifica importante o che sarà un collaboratore frequente a un repository. I collaboratori frequenti in genere hanno modifiche in corso o a esecuzione prolungata che passano attraverso più cicli di compilazione/convalida/staging o durano più giorni prima di disconnettersi dalla richiesta pull.

Alcuni esempi di questo tipo di contributi includono:

Proposta di contributi estesi. Ad esempio, i contributi (aggiunte, modifiche o eliminazioni) possono estendersi su più articoli ed eseguire il commit e il test come 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.
L'aggiunta di nuove immagini o l'aggiornamento di immagini, che in genere richiede di creare contemporaneamente una nuova media sottodirectory, creare file di immagine, aggiornare i collegamenti alle immagini negli articoli e visualizzare in anteprima i 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. Si rischia anche di perdere le modifiche se si esegue questa operazione tramite l'editor Web GitHub e attendere prima di eseguire il commit delle modifiche.
Aggiornamento continuo dello stesso articolo dopo l'apertura di una richiesta pull. Anche se a questo scopo è possibile usare l'editor Web GitHub, è possibile creare più richieste pull in sospeso per lo stesso file, che possono essere in conflitto tra loro.

Prerequisiti

Identificare il repository GitHub che archivia la documentazione da modificare.
Creare un account GitHub, se non ne è disponibile uno.
Installare gli strumenti Git e Markdown.
Configurare un repository Git locale.
Esaminare i concetti fondamentali su Git e GitHub (facoltativo).

Creare ed eseguire il check-out del ramo di lavoro

Per iniziare, creare un nuovo ramo di lavoro nel repository locale per acquisire le modifiche proposte. Per altre informazioni sui rami, vedere Nozioni fondamentali su Git e GitHub.

Questa esercitazione usa Git Bash e Visual Studio Code, ma è possibile usare qualsiasi client Git e editor preferito.

In VS Code aprire la cartella del repository del clone locale. Dal menu File selezionare Apri cartella e passare alla cartella nel computer.
Selezionare Visualizza dal menu in alto e quindi selezionare Terminale per aprire il terminale integrato.
Nel terminale integrato assicurarsi di essere nella cartella del repository.
Prima di creare un ramo di lavoro, assicurarsi che il ramo principale locale sia corrente con tutti gli elementi nel ramo principale del repository di produzione. Questa attività garantisce che il ramo di lavoro acquisisca tutte le modifiche apportate nel repository di produzione dall'ultima sincronizzazione con esso.
1. Passare al ramo main nel repository locale:
```
git checkout main 
```
2. Verificare che il ramo main locale sia corrente:
```
git pull upstream main 
```
Creare un ramo di lavoro locale basato su main:
```
git checkout -b <branch-name>
```
<branch-name> è un segnaposto. Quando si esegue il comando, sostituirlo con un nome univoco e significativo per il ramo e rimuovere le parentesi angolari.
Eseguire il push del ramo di lavoro locale nel ramo remoto nel fork di GitHub:
```
git push origin <branch-name> -u
```
L'opzione -u collega i rami locali e remoti. Questa opzione consente di eseguire il push dei commit nel fork immettendo solo git push anziché git push origin <branch-name>.

Trovare il file Markdown di origine

Per modificare un articolo, trovare il file di origine per l'articolo nel clone del repository locale. In VS Code accedere ai file Markdown del repository tramite Esplora file (un'icona del documento nella barra laterale superiore sinistra). Esplora file mostra la struttura di cartelle del repository ed è possibile passare al file da modificare.

Se non è possibile trovare il file, visitare l'articolo su Microsoft Learn e selezionare l'icona a forma di matita Modifica . Il percorso della cartella relativa nel repository GitHub viene visualizzato nell'URL. Di seguito è riportato un esempio di URL di collegamento edit :

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Ecco un percorso di file di esempio per questo URL.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Modificare il file

Aprire il file in VS Code selezionandolo.
Apporta le modifiche desiderate.
Salvare le modifiche selezionando File>Salva. Usare Salva tutto per salvare più file contemporaneamente.

Eseguire il commit e il push delle modifiche

Se sono state apportate modifiche sostanziali o è stato esaminato un articolo per l'aggiornamento, aggiornare ms.date il blocco di metadati nella parte superiore del file. Formattare la data come mm/gg/aaaa.

È possibile usare il terminale di VS Code o l'interfaccia utente di VS Code per eseguire il commit e il push delle modifiche.

Terminale di VS Code
Interfaccia utente di VS Code

Eseguire il git status comando per verificare che nell'elenco dei file modificati vengano visualizzati solo i file modificati.
```
git status
```
Eseguire il git add comando seguito dal percorso del file e dal nome del file per preparare il file modificato.
```
git add folder-name/file-name.md
```
Se sono stati modificati più file, immettere un git add comando per ogni file.

In alternativa, è possibile eseguire (annotare git add . il periodo dopo add) per preparare automaticamente tutte le modifiche apportate. Questo metodo è più veloce, ma può causare problemi includendo le modifiche apportate per errore.
Eseguire git status di nuovo per confermare le modifiche di cui è stata eseguita la gestione temporanea.
Eseguire il git commit comando seguito da un messaggio di commit per salvare le modifiche nel repository clonato locale.
```
git commit -m "your commit message"
```
Eseguire git push per eseguire il push delle modifiche.
```
git push
```

È possibile creare ed eseguire il push di un commit usando le funzionalità di integrazione Git di VS Code. Ricordarsi di continuare il lavoro nello stesso computer. Se si cambia computer, non sarà disponibile la versione più recente del ramo di lavoro per continuare.

Assicurarsi che il repository locale abbia ancora lo stesso ramo di lavoro estratto. Nell'interfaccia utente di VS Code il ramo viene visualizzato nell'angolo inferiore sinistro. Il nome del ramo funziona anche come pulsante per il cambio di rami.
Nella barra laterale sinistra di VS Code selezionare lo strumento fork per visualizzare il riquadro Controllo del codice sorgente: Git .

Il file modificato viene visualizzato in Modifiche con un M a destra per indicare che è stato modificato. I nuovi file vengono visualizzati con un U (non registrato) e i file eliminati vengono visualizzati con un D.
Preparare le modifiche. Passare il puntatore del mouse sulla riga Modifiche fino a quando non viene visualizzata un'icona + . Selezionare l'icona. Questa azione equivale al git add comando . Il file viene ora visualizzato nella sezione Modifiche a fasi.
Immettere un messaggio di commit, ad esempio "aggiorna data metadati" nella casella di testo Messaggio e selezionare il segno di spunta.
Eseguire il push del commit. Selezionare il pulsante Sincronizza modifiche visualizzato sotto il blocco di messaggi di commit.

Il processo è completo. Il codice è ora disponibile nel repository GitHub e pronto per l'apertura di una richiesta pull.

Se è necessario apportare una correzione nel materiale inviato, È facile! Ripetere i passaggi precedenti, a partire da Modifica il file, per apportare modifiche nello stesso ramo e quindi eseguire di nuovo il commit e il push (non è necessario configurare il server upstream nei push successivi dello stesso ramo). In genere, i rami vengono usati per separare i flussi di lavoro, quindi non è necessario creare un nuovo ramo, a meno che non si sia pronti a lavorare su un altro elemento.

Apportare la modifica successiva

Pronto a apportare un'altra modifica, non correlata a questa? Tornare al ramo predefinito, eseguire il pull dal repository upstream per aggiornare il fork ed estrarre un nuovo ramo. Eseguire i comandi seguenti in Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

Si è ora in un nuovo ramo collegato al ramo remoto e si è pronti per apportare altre modifiche. Stai bene nel tuo modo di diventare un collaboratore esperto!

Passaggi successivi

Se sono stati completati i passaggi precedenti, è ora possibile aprire una richiesta pull per unire le modifiche nel ramo principale.
Per altre informazioni su argomenti come la sintassi delle estensioni Markdown e Markdown, vedere le informazioni di riferimento su Markdown.

Condividi tramite