Nozioni di base sulla documentazione Git e GitHub
Panoramica
Se si desidera apportare solo modifiche secondarie testuali agli articoli, non è necessario comprendere i dettagli del presente articolo. Il presente articolo descrive il flusso di lavoro per l’applicazione di modifiche principali, ad esempio la creazione di nuovi articoli, l’aggiunta di immagini o l’applicazione di modifiche continuative alla documentazione di Adobe.
In qualità di collaboratore al contenuto della documentazione di Adobe, puoi interagire con più strumenti e processi. Puoi lavorare in parallelo con altri collaboratori sullo stesso progetto, potenzialmente lo stesso contenuto, anche nello stesso momento. Tutto ciò è consentito dal software Git e GitHub.
Git è un sistema di controllo della versione open source che consente la collaborazione. Più collaboratori possono lavorare su file che risiedono in degli archivi.
GitHub è un servizio di hosting basato su Web per archivi Git, come ad esempio quelli utilizzati per archiviare il contenuto di docs.adobe.com. Per qualsiasi progetto, GitHub ospita l’archivio principale, dal quale i collaboratori possono effettuare copie per il proprio lavoro.
Git
Git dispone di un flusso di lavoro e di una terminologia univoci per supportare il proprio modello distribuito. Ad esempio, non esiste un blocco file normalmente associato alle operazioni di check-out/check-in. Git consente di risolvere le modifiche a un livello ancora più preciso, confrontando i file byte per byte.
Git utilizza inoltre una struttura a livelli per archiviare e gestire il contenuto per un progetto:
- Archivio: anche noto come repo o repository, è l’unità di archiviazione di livello più alto. Un archivio contiene uno o più rami.
- Ramo: tutti gli archivi contengono un ramo predefinito (in genere denominato “principale”) e uno o più rami destinati a essere uniti nuovamente al ramo principale. Il ramo principale rappresenta la versione corrente e l’origine da cui il contenuto viene pubblicato. È l’elemento superiore da cui vengono creati tutti gli altri rami nell’archivio.
I collaboratori interagiscono con Git per aggiornare e manipolare archivi a livello locale e di GitHub:
- Localmente mediante strumenti quali GitHub Desktop.
- Tramite www.github.com, che integra Git per gestire la riconciliazione dei contributi che torneranno nell’archivio principale.
GitHub
Tutti i flussi di lavoro iniziano e terminano a livello di GitHub, dove viene conservato l’archivio principale per qualsiasi progetto della documentazione di Adobe. Le copie create dai collaboratori per il proprio utilizzo vengono distribuite su più computer. Tali copie vengono infine riconciliate nell’archivio GitHub principale del progetto.
Organizzazione della directory
Il ramo predefinito/principale di un progetto rappresenta la versione corrente del contenuto del progetto. Il contenuto del ramo principale (e dei rami creati da esso) è allineato all’organizzazione degli argomenti dell’articolo. Le sottodirectory vengono utilizzate per organizzare il contenuto e le risorse immagine.
Di solito è possibile trovare una directory help principale dalla radice dell’archivio. La directory degli articoli contiene un set di sottodirectory. Gli articoli nelle sottodirectory vengono formattati come file Markdown che utilizzano un’estensione .md.
Nella radice di tale directory, puoi trovare articoli generali che si riferiscono al servizio o al prodotto generale. In genere, puoi trovare un’altra serie di sottodirectory che corrispondono a funzioni/servizi o scenari comuni.
Directory risorse
Le directory della guida utente contengono sottodirectory /assets per i file immagine a cui si fa riferimento all’interno di una directory.
Richieste di pull
Una richiesta di pull consente a un collaboratore di proporre in modo pratico un insieme di modifiche da applicare al ramo predefinito. Le modifiche (dette anche proposte) vengono archiviate nel ramo di un collaboratore, così da consentire per prima cosa a GitHub di modellare l’impatto della loro unione al ramo predefinito. Una richiesta di pull funge anche da meccanismo per fornire al collaboratore un feedback da un processo di creazione/convalida o dal revisore di una richiesta di pull, per risolvere potenziali problemi o domande prima che le modifiche vengano unite al ramo predefinito.
Vi sono due modi per contribuire tramite richiesta di pull, in base alla portata delle modifiche che desideri proporre. Tale descrizione verrà fornita in dettaglio più avanti, nella sezione Flusso di lavoro GitHub della presente guida.