Apportare modifiche importanti alla documentazione di Microsoft Learn

  • Articolo

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 learn.microsoft.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

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.

  1. In VS Code aprire la cartella del repository del clone locale. Dal menu File selezionare Apri cartella e passare alla cartella nel computer.

  2. Selezionare Visualizza dal menu in alto e quindi selezionare Terminale per aprire il terminale integrato.

  3. Nel terminale integrato assicurarsi di essere nella cartella del repository.

  4. 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

  5. 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.

  6. 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

  1. Aprire il file in VS Code selezionandolo.
  2. Apporta le modifiche desiderate.
  3. 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.

  1. Eseguire il git status comando per verificare che nell'elenco dei file modificati vengano visualizzati solo i file modificati.

    git status

  2. 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.

  3. Eseguire git status di nuovo per confermare le modifiche di cui è stata eseguita la gestione temporanea.

  4. 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"

  5. Eseguire git push per eseguire il push delle modifiche.

    git push

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