Documentazione di Git e GitHub per Microsoft Learn

  • Articolo

Panoramica

In qualità di collaboratore alla documentazione di Microsoft Learn, si interagirà con più strumenti e processi. lavorando parallelamente ad altri collaboratori sullo stesso progetto, potenzialmente sullo stesso contenuto, persino nello stesso tempo. Tutto ciò è reso possibile dal software Git e GitHub.

Git è un sistema di controllo delle versioni open source che facilita questo tipo di collaborazione ai progetti tramite il controllo delle versioni distribuito dei file archiviati in repository. In sintesi, Git rende possibile l'integrazione dei flussi di lavoro svolto da più collaboratori nel tempo per un determinato repository.

GitHub è un servizio di hosting basato sul Web per i repository Git, ad esempio quelli usati per archiviare il contenuto di Microsoft Learn . Per ogni progetto, GitHub ospita il repository principale, dal quale i collaboratori possono creare copie per il loro lavoro,

Questo articolo definisce i termini chiave che fanno parte del flusso di lavoro di Microsoft Learn. Offre anche una panoramica dei repository Git e GitHub e spiega come è organizzato il contenuto per la documentazione tecnica Microsoft.

Filiale

I rami separano flussi di lavoro, in genere definiti versioni. I contributi vengono sempre creati in un ramo specifico, che ne rappresenta anche l'ambito.

L'isolamento delle modifiche correlate a un ramo specifico consente di controllare e introdurre tali modifiche in modo indipendente. 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.

Tutti i repository contengono un ramo predefinito (in genere denominato "main") e uno o più rami di lavoro in corso (che chiamiamo rami di lavoro) che non sono ancora stati integrati nel 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.

Ogni volta che si introduce un nuovo set di modifiche correlate logicamente, è consigliabile creare un ramo di lavoro per gestire le modifiche. Non è consigliabile apportare direttamente modifiche al ramo predefinito.

Fork

Questo termine viene in genere usato come sostantivo quando si fa riferimento a una copia di un repository GitHub principale. In pratica, un fork è semplicemente un altro repository, ma è speciale perché GitHub mantiene un collegamento con il repository principale/padre. Questo termine viene talvolta usato come verbo, come in "È necessario creare prima una copia tramite fork del repository".

Git

Se si ha familiarità con i sistemi di controllo della versione centralizzati (ad esempio Team Foundation Server , SharePoint o Visual Source Cassaforte), Si noterà che Git ha un flusso di lavoro e una terminologia univoci per il contributo per supportare il modello distribuito. Ad esempio, non esiste alcun blocco di file normalmente associato alle operazioni di estrazione/archiviazione. Git è invece preoccupato per le modifiche a un livello ancora più fine, confrontando i byte di byte dei file.

Git usa anche una struttura su più livelli per l'archiviazione e la gestione del contenuto per un progetto:

  • Repository: noto anche come repo, è l'unità di archiviazione di livello più alto. Un repository contiene uno o più rami.
  • Ramo: unità di archiviazione che contiene i file e le cartelle che costituiscono il set di contenuti di un progetto. Per altre informazioni sui rami, vedere la sezione Branch di questo articolo.

I collaboratori interagiscono con Git per aggiornare e modificare i repository sia a livello locale che di GitHub:

  • A livello locale tramite strumenti come la console di Git Bash, che supporta comandi Git per la gestione dei repository locali e la comunicazione con i repository di GitHub.
  • Tramite www.github.com, che integra Git per gestire la riconciliazione dei contributi che confluiscono nel repository principale.

GitHub

Nota

Anche se le indicazioni sulla documentazione si basano sull'uso di GitHub, alcuni team usano Visual Studio Team Services per ospitare i repository Git. Il client Visual Studio Team Explorer offre un'interfaccia utente grafica per l'interazione con i repository di Team Services, in alternativa all'uso dei comandi Git tramite la riga di comando.
Inoltre, molte delle linee guida seguenti sono state sviluppate come procedure consigliate da anni di esperienza nell'hosting del contenuto del servizio di Azure in GitHub. Potrebbero essere necessari in alcuni repository di Microsoft Learn.

Tutti i flussi di lavoro iniziano e terminano a livello di GitHub, in cui è archiviato il repository principale per qualsiasi progetto di documentazione. Le copie che i collaboratori creano per uso personale vengono distribuite tra più computer e alla fine vengono riconciliate nel repository GitHub principale del progetto.

Organizzazione delle directory

Il ramo predefinito di un progetto funge da versione corrente del contenuto per il progetto. Il contenuto nei rami e nei rami predefiniti creati da esso è allineato in modo libero all'organizzazione degli articoli nelle pagine di Microsoft Learn corrispondenti. Le sottodirectory vengono usate per separare come gli articoli (ad esempio i servizi), il contenuto multimediale (ad esempio i file di immagine) e i file "include" (che consentono il riutilizzo del contenuto).

Sottodirectory articles

È in genere possibile trovare una directory articles principale dalla radice del repository. La articles directory contiene un set di sottodirectory Articoli nelle sottodirectory vengono formattati come file Markdown che usano un'estensione md . Alcuni repository che supportano più servizi usano una sottodirectory /articles generica, come il repository Azure-Docs. Altri potrebbero usare un nome specifico del servizio, ad esempio il repository IntuneDocs che usa /IntuneDocs.

Alla radice di questa directory sono disponibili gli articoli generali correlati al servizio o al prodotto nel suo insieme. Esiste in genere un'altra serie di sottodirectory corrispondenti a funzionalità/servizi o scenari comuni. Ad esempio, gli articoli relativi alle macchine virtuali di Azure sono inclusi nella sottodirectory /virtual-machines e gli articoli dedicati ai concetti e all'esplorazione di Intune sono nella sottodirectory /understand-explore.

Sottodirectory media

Ogni directory di articoli contiene una sottodirectory /media per i file multimediali corrispondenti. I file multimediali contengono le immagini usate dagli articoli che includono riferimenti a immagini.

Sottodirectory includes

L'eventuale contenuto riutilizzabile condiviso da due o più articoli viene posizionato in una sottodirectory /includes all'interno della directory articles principale. In un file markdown che usa il file di inclusione viene inserita un'estensione Markdown "include" corrispondente nel punto in cui è necessario fare riferimento al file di inclusione.

Per altre indicazioni, vedere Le informazioni di riferimento su Markdown: include .

Modello di file markdown

Per comodità, la directory radice di ogni repository contiene in genere un file modello Markdown denominato template.md. Se è necessario creare un nuovo articolo per l'invio al repository, è possibile partire da questo file. Il file contiene:

  • Un'intestazione metadati all'inizio del file, delimitata da due linee a 3 trattini. L'intestazione contiene i vari tag usati per tenere traccia delle informazioni correlate all'articolo. I metadati dell'articolo consentono alcune funzionalità, ad esempio l'attribuzione dell'autore e/o del collaboratore, i percorsi di navigazione e le descrizioni dell'articolo. Includono anche le ottimizzazioni SEO e i processi di creazione di report usati da Microsoft per valutare le prestazioni del contenuto. I metadati sono quindi importanti.
  • Una sezione metadati che descrive i vari tag e i diversi valori dei metadati. Se non si conoscono con certezza i valori da usare per la sezione metadati, è possibile non specificarli o impostarli come commenti con un hashtag iniziale (#). Verranno esaminati o completati dal revisore della richiesta pull per il repository.
  • Diversi esempi di uso di Markdown per formattare gli elementi di un articolo.
  • Istruzioni generali sull'uso delle estensioni Markdown per diversi tipi di avvisi.
  • Esempi di incorporamento di video tramite un iframe.
  • Istruzioni generali sull'uso delle estensioni della documentazione tecnica Microsoft, che è possibile usare per controlli speciali, ad esempio pulsanti e selettori.

Origine

Questo termine è il nome assegnato alla connessione tra il repository locale e il repository da cui è stato clonato. Nel flusso di lavoro di Microsoft Learn l'origine rappresenta la connessione al fork. Questo termine viene talvolta usato come moniker per il repository di origine stesso, come in "Ricordarsi di eseguire il push delle modifiche all'origine".

Richieste pull

Una richiesta pull (PR) è una richiesta per il pull delle modifiche apportate all'origine ufficiale da parte di un proprietario del contenuto. Una richiesta pull consente il pull e il merge del modello di collaborazione di GitHub richiedendo le modifiche (note anche come commit) dal ramo di lavoro. Nella maggior parte dei casi, tale altro ramo è il ramo predefinito nel repository principale.

Una richiesta pull funge anche da meccanismo per fornire al collaboratore feedback dai processi di convalida di Microsoft Learn e dal revisore della richiesta pull per risolvere i problemi o le domande prima che le modifiche vengano unite nel ramo predefinito.

Remoto

Una connessione remota è una connessione denominata a un repository remoto, ad esempio "origin" o "upstream". Git fa riferimento a questo come remoto perché viene usato per fare riferimento a un repository ospitato in un altro computer. Nel flusso di lavoro di Microsoft Learn, un repository remoto è sempre un repository GitHub.

Upstream

Analogamente all'origine remota, upstream è una connessione denominata a un altro repository. Nel flusso di lavoro di Microsoft Learn, upstream rappresenta la connessione tra il repository locale e il repository principale da cui è stato creato il fork. Questo termine viene talvolta usato come moniker per il repository upstream stesso, come in "Ricordarsi di eseguire il pull delle modifiche più recenti dall'upstream".

Altre informazioni

Se non si ha familiarità con Git o GitHub, queste risorse possono essere utili per imparare, essere produttivi o rispondere a domande.

Risorse di controllo del codice sorgente Git

Risorse di GitHub

Domande frequenti

Che cos'è Git?

Git consente di tenere traccia delle modifiche quando molte persone lavorano insieme sul codice del computer. È come una macchina temporale per il codice, quindi è possibile vedere cosa è cambiato e tornare indietro, se necessario.

Perché usare Git?

È fantastico per il lavoro in team. Git semplifica il lavoro di un sacco di persone nello stesso progetto senza creare confusione tra loro. Aiuta anche a correggere facilmente gli errori.

Come funziona Git?

Git archivia tutte le versioni del codice di un progetto. Quando si apportano modifiche, Git acquisisce un'immagine (ad esempio uno snapshot) delle differenze. È possibile creare versioni diverse contemporaneamente senza problemi.

Che cosa sono i rami in Git?

I rami sono simili a percorsi diversi in un progetto. Consentono alle persone di lavorare su cose nuove senza modificare il progetto principale. In un secondo momento, possono riportare queste modifiche nel progetto principale.

Che cos'è un commit in Git?

Un commit è simile a un punto di salvataggio. È un modo per registrare le modifiche apportate. Ogni commit ha un ID univoco e una nota su ciò che è stato modificato.

Che cos'è GitHub?

GitHub è un sito Web in cui è possibile archiviare i progetti Git. È come un grande hub per condividere e lavorare insieme al codice con altri utenti. Aiuta anche a tenere traccia di chi ha cambiato cosa.

In che modo GitHub è diverso da Git?

Git è lo strumento per tenere traccia delle modifiche, mentre GitHub è la posizione in cui archiviare i progetti e collaborare. GitHub usa Git per eseguire la sua magia.

GitHub è gratuito?

Sì, per i progetti che tutti possono vedere. Ma per i progetti privati (solo l'utente e il team), potrebbe essere necessario pagare. Offrono piani diversi con funzionalità aggiuntive.

Che cosa sono le richieste pull in GitHub?

Le richieste pull sono come chiedere di inserire le modifiche nel progetto principale. Persone possibile esaminare e discutere le modifiche prima che vengano aggiunte.

Quanto è sicuro GitHub?

GitHub si occupa della sicurezza. Usano codici e regole speciali per assicurarsi che solo le persone giuste possano accedere e modificare il codice. È anche possibile aggiungere livelli di sicurezza aggiuntivi come l'autenticazione a due fattori per una maggiore sicurezza.