Nozioni fondamentali sui contributi per Microsoft Learn

Completato

Per comprendere e completare il processo di contribuzione, prima di tutto è importante apprendere alcuni termini. Non è necessario conoscere tutto ciò che accade dietro le quinte, ma una panoramica generale serve a capire perché il processo di collaborazione funziona in un determinato modo.

Nozioni fondamentali su Microsoft Learn e GitHub

Microsoft Learn contiene migliaia di articoli, moduli di formazione, pagine Web e altro ancora, che devono essere archiviati e utilizzati regolarmente da vari collaboratori. Microsoft Learn usa GitHub per archiviare gran parte di questo contenuto. GitHub è una piattaforma che si basa su Git, un sistema di controllo della versione distribuito, che consente di archiviare i progetti e facilitare la collaborazione tra più stakeholder, ciascuno con obiettivi e tempistiche di progetto differenti. Il software di Git e di GitHub consente di lavorare in parallelo con altri collaboratori sullo stesso progetto, potenzialmente sullo stesso identico contenuto, anche contemporaneamente, senza interferire involontariamente con il lavoro degli altri.

Il contenuto viene archiviato in file all'interno di repository Git ospitati su GitHub. Un repository è un'unità di archiviazione che contiene i file di un progetto e la cronologia delle revisioni dei file. I repository possono essere pubblici o privati e Microsoft Learn è costituito da una combinazione di entrambi. Chiunque può contribuire a un repository pubblico dopo aver configurato un account GitHub. I repository privati sono disponibili solo per i collaboratori che sono dipendenti Microsoft o che hanno ottenuto un'autorizzazione speciale.

Apportare modifiche al contenuto di Microsoft Learn archiviato in un repository GitHub

Per qualsiasi progetto, GitHub ospita il repository principale ed eventuali fork. Un fork è una copia del repository principale creata da un collaboratore per il proprio lavoro. Un fork è uno dei modi in cui GitHub protegge il contenuto pubblicato. Anziché permettere la modifica diretta del contenuto nel ramo attivo pubblicato del repository principale, GitHub crea uno snapshot del contenuto per il fork, in cui apportare le modifiche.

I repository GitHub contengono uno o più rami. Un ramo è un'unità di archiviazione che contiene i file e le cartelle che compongono il set di contenuti di un progetto. Tutti i repository, che si tratti del repository principale o di un fork, contengono un ramo predefinito (in genere denominato principale) e uno o più rami destinati a essere uniti al ramo predefinito. Il ramo predefinito funge da versione corrente e da unica origine di riferimento per il progetto. e rappresenta il ramo padre da cui vengono creati tutti gli altri rami nel repository.

Apparentemente, la modifica di un articolo della documentazione in un repository pubblico inizia selezionando un pulsante. In realtà, in secondo piano si verificano varie operazioni. Quando si avvia il processo di modifica basato su browser, viene creato un fork del repository (se non ne è già stato creato uno), che verrà usato per le modifiche. Le modifiche si apportano all'interno di un ramo del fork, che verrà successivamente unito al ramo live del repository principale, in modo che le modifiche siano disponibili per tutti.

Crea una richiesta pull

Come avviene l'unione? È necessario informare GitHub, e in particolare i proprietari del repository principale e gli autori dell'articolo, che le modifiche sono state completate e sono pronte per la revisione e la pubblicazione! A questo scopo, occorre creare e inviare una richiesta pull.

Una richiesta pull è una proposta di unione delle modifiche dal ramo nel fork su cui si sta lavorando al ramo principale predefinito del repository live. Quando si lavora in un repository pubblico, le richieste pull sono sempre esaminate da un revisore umano prima dell'unione. Potrebbero anche essere eseguiti dei controlli automatizzati, ad esempio la compatibilità dell'unione e la convalida della compilazione. Una volta completate queste revisioni e risolti gli eventuali problemi, le modifiche vengono unite al ramo live e diventano disponibili in Microsoft Learn!

Flusso di lavoro per i contributi di lieve entità alla documentazione

In sintesi, per apportare piccole modifiche alla documentazione Microsoft usando l'editor Web in GitHub si seguiranno questi passaggi generali:

1. Quando si apre un file nel browser per modificarlo, viene creato automaticamente un fork del repository pubblico. Viene inoltre creato un ramo nel fork, spesso denominato ramo patch.
2. Apportare le modifiche al file.
3. Creare una richiesta pull per proporre che le modifiche vengano riviste e unite.
4. La richiesta pull deve risolvere gli eventuali problemi e superare tutte le revisioni.
5. La richiesta pull viene unita al ramo principale del repository live e le modifiche vengono pubblicate su Microsoft Learn.

Passiamo ora a esaminare in dettaglio i singoli passaggi.