Guida per principianti a GitHub

Questo documento è una guida semplice e scarna per portarla da "Che cosa è Git?" a "Tutti dovrebbero usare la mia scheda del personaggio nuova di zecca!" il più rapidamente possibile, senza cercare di insegnarle tutte le complessità di cui il sistema è capace. Git è un software di controllo di versione, ma questa guida ignorerà totalmente come può utilizzarlo per tracciare le sue modifiche, e si concentrerà esclusivamente sullo spostamento dei suoi aggiornamenti nei repository master di Roll20. La sezione "Ulteriori informazioni" contiene link a guide sul funzionamento di Git/GitHub di carattere generale.


Che cos'è Git/GitHub?

Gitè un software che lei installa localmente sul suo computer e che gestisce il controllo di versione per lei. GitHubè un servizio di hosting perrepository Git. Quindi non sono la stessa cosa:Gitè lo strumento,GitHubè il servizio per i progetti che utilizzanoGitBreve confronto.

Esistono diversi modi per utilizzare Git. Git è molto potente, ma per poterlo sfruttare al meglio deve imparare ad usare la shell di comando (xkcd comic). La sezione "Ulteriori informazioni" in basso contiene ulteriori letture sulla shell di comando per coloro che sono interessati. Tuttavia, tutto ciò che verrà illustrato in questo documento può essere fatto utilizzando solo l'interfaccia grafica GitHub Desktop (molto utile per mantenere il disco rigido del suo computer sincronizzato con il suo repository - vedere "Clonare il suo repository" di seguito) e gli strumenti web di GitHub, che sono entrambi strumenti semplificati per utilizzare il Git sottostante.


Configurazione di GitHub

Creare il suo account

Per utilizzare GitHub, deve avere un account sul loro sito web. Può creare un account a pagamento o un account gratuito. A meno che non intenda creare un gran numero di progetti che non vuole condividere con il mondo, non c'è motivo di creare un account a pagamento: l'unica differenza tra i vari livelli di prezzo è il numero di repository privati che le è consentito avere. Tutti, compresi gli account gratuiti, possono avere un numero illimitato di repository pubblici.

Avrà a che fare con i repository master di Roll20 per i fogli dei personaggi e/o gli script di roll20-api, che sono repository pubblici. Creerà anche un fork di questi repository, che potrebbero anche essere pubblici, quindi per gli usi di Roll20, un account gratuito è tutto ciò che le serve.


FORK il repository ufficiale di Roll20

Un fork diè una copia di un repository. Il fork di un repository le permette di sperimentare liberamente le modifiche senza influenzare il progetto originale.
roll20-character-sheets" è il repository dei fogli dei personaggi. Per gli script API, si colleghi a "roll20-api-scripts".

Il fork è facilmente realizzabile utilizzando gli strumenti web di GitHub. Clicchi sul pulsante Fork del repository ufficiale situato all'indirizzohttps://github.com/Roll20/roll20-character-sheetsohttps://github.com/Roll20/roll20-api-scripts, a seconda dei casi. Questo creerà una copia di quel repository nel suo account, che avrà il permesso di modificare a suo piacimento. Leipuòfare il fork del repository quante volte vuole, ma devefare il fork una sola volta. Questo nuovo repository avrà un indirizzo identico a quello originale, ma invece di avere come radice "Roll20" avrà come radice il nome del suo account Roll20.

Se sta lavorando con un altro utente sullo stesso foglio o script, potrebbe essere una buona idea entrare nelle impostazioni del suo nuovo repository e aggiungerlo come collaboratore. I dettagli su come aggiungere un collaboratore o lavorare con un collaboratore esulano tuttavia dallo scopo di questo tutorial.

Se ha familiarità con il sistema di controllo di versione Git, non dovrebbe avere bisogno di altre informazioni per completare l'invio della scheda del personaggio. Tutti gli altri, continuino a leggere!


CLONA il suo repository

Clonazioneun repository crea anche una copia, ma un repository clonato viene utilizzato come copia di lavoro e si trova sul disco rigido del computer locale come normali cartelle e file. Git mantiene un collegamento - per impostazione predefinita denominato "origine" - tra le cartelle e il repository da cui è stato clonato.
L'elenco includerà tutti i repository del suo account.

Per gli utenti Git principianti, si raccomanda vivamente di scaricare e installareGitHub per WindowsoGitHub per Mac, a seconda del sistema operativo. In questo documento ci si riferirà a loro come "GitHub Desktop" o "l'applicazione desktop". Oltre ad essere un modo semplice per installare e configurare il controllo di versione Git sul suo computer, le applicazioni desktop di GitHub facilitano il collegamento al suo account utente GitHub. Le dirà quando i suoi file sul computer non sono aggiornati con il suo repository su GitHub e le permetterà di sincronizzare facilmente i due.

Quando esegue per la prima volta l'applicazione GitHub, le chiederà di accedere al suo account GitHub. Quindi, clicchi sul grande segno più in alto a sinistra per Clonare il suo repository. Quando clona il repository, le verrà richiesto di selezionare una posizione in cui inserire i file. Si assicuri di selezionare un luogo che possa trovare facilmente, dovrà sapere dove si trova! Se prende un nuovo computer, l'installazione del desktop GitHub e la clonazione del suo repository sono l'unico passaggio da ripetere.

L'applicazione desktop ha anche l'interfaccia più semplice per la gestione delle Filiali. Quando cambia ramo all'interno dell'applicazione desktop, aggiungerà / rimuoverà / modificherà i file in modo che corrispondano all'ultimo commit effettuato dal ramo a cui è passato.

Se non sta utilizzando l'applicazione GitHub, può trovare l'url di clonazione del suo repository nella pagina del suo repo. GitHub offre sia gli url di clone SSH e HTTPS, sia l'url di checkout di Subversion. I dettagli della clonazione manuale del suo repo esulano tuttavia dallo scopo di questa guida. 


Flusso di lavoro per la biforcazione su GitHub

La configurazione di cui sopra viene eseguita solo una volta. La sezione seguente descrive le procedure che si consiglia di seguire ogni volta che desidera inviare un aggiornamento a Roll20.


Sincronizzi i suoi file con Roll20

Se ha appena fatto il fork e clonato il suo repository pochi minuti fa, è ancora sincronizzato. Ma se torna al repository dopo molte settimane o mesi, alcuni fogli dei personaggi o script API saranno stati aggiornati. È possibile che quello che desidera modificare sia tra questi. In questo caso, deve assicurarsi di lavorare con la versione più recente dei file che modificherà. Nondeve creare un altro fork, né deve clonare nuovamente il suo repository. Dovrà aggiornare il suo fork con master. Legga la guida linkata qui di seguito su come sincronizzare

Piuttosto che fare una sincronizzazione, che sia necessaria o meno, potrebbe desiderare di vedere prima se è necessario sincronizzare il progetto o i progetti su cui lavorerà. Un controllo semplice è quello di guardare i file nel repository di Roll20 e vedere la data dell'ultima modifica. Un'altra possibilità è quella di aprire i file lì ed eseguire un'utility"diff"su di essi e sulla sua versione più recente. Verifichi se ci sono richieste di Pull in sospeso per i file che intende aggiornare. Se i file specifici che modificherà sono rimasti invariati rispetto all'ultima sincronizzazione, l'esecuzione di una sincronizzazione completa di tutto è facoltativa.

Un'altra opzione è quella di prelevare tutti gli aggiornamenti dal repository master di Roll20. In questo modo otterrà tutti gli aggiornamenti che altre persone hanno apportato ai repository di roll20 dall'ultima volta che li ha sincronizzati (compresi alcuni fogli di personaggi o script API che potrebbero non interessarle). Questo link hauna guida per sincronizzare il suo repository con Original. Al termine di questa operazione, i file nel repository master di Roll20, nel suo repository personale e sul suo disco rigido dovrebbero essere tutti uguali. Si assicuri di aggiornare anche la sua campagna roll20. 


Creare un ramo

Si raccomanda di creare un nuovo ramo per ogni progetto separato (scheda personaggio o script API) e per ogni aggiornamento separato. Per esempio, se deve aggiornare due diversi script API contemporaneamente, crei un ramo per ogni script. Se qualche settimana dopo decide di apportare ulteriori modifiche allo stesso script, crei un nuovo ramo per l'aggiornamento più recente. Come regola generale, crei un nuovo ramo per ogni richiesta di pull.

L'applicazione desktop ha anche l'interfaccia più semplice per la gestione delle Filiali. Nel menu in alto, scelga "Filiale / Nuova filiale". Quando cambia ramo all'interno dell'applicazione desktop (la seconda riga le permette di cambiare il repository su cui sta lavorando e di cambiare il ramo corrente), aggiungerà/rimuoverà/modificherà i file sul suo disco rigido in modo che corrispondano all'ultimo commit effettuato dal ramo a cui è passato.

GitHub Compare.png


IMPEGNARE le sue modifiche e SPINGERE i suoi commit

Quando leiesegue il commit delle modifiche di, memorizza sul suo computer locale un record di tutto ciò che ha modificato, nonché una descrizione leggibile dall'uomo di ciò che ha fatto. 
Quindipushi suoi commit al suo repository.

Una volta clonata una copia funzionante del suo repository, può apportarvi delle modifiche. Questo include la creazione di una nuova cartella per la scheda del personaggio o per lo script API e l'aggiunta del codice sorgente ad essa, oppure le modifiche ai file già presenti.

Molte persone, quando sviluppano i copioni di Roll20 o le schede dei personaggi, fanno tutte le modifiche effettive in un editor di testo (ad esempio notepad++). Può semplicemente aprire i file sul suo disco rigido (quelli creati nella fase 'clone') in qualsiasi editor di testo e apportare le modifiche nell'editor. Ogni volta che desidera eseguire il codice su Roll20, prema ctrl/a e ctrl/c per selezionare tutto il testo e copiarlo negli appunti. Poi lo incolli nel campo corretto della campagna di Roll20. Se sono necessarie ulteriori modifiche (ad esempio per il debug), spesso è più facile eseguire continuamente un ciclo di modifica, copia, incolla e prova.

Quando ordina all'editor di testo di salvare le sue modifiche, questo scriverà finalmente le sue modifiche nel file che ha modificato, e GitHub Desktop rileverà che il file che ha modificato è cambiato e visualizzerà il nome del file che è cambiato nel suo riquadro di sinistra, e nel riquadro di destra visualizzerà un riepilogo di ciò che rileva come diverso tra il salvataggio attuale e l'ultimo commit effettuato. Tuttavia, queste modifiche sono state solo rilevate, GitHub non registra effettivamente queste modifiche fino a quando lei non effettua il commit. Gli esperti di Git raccomandano di eseguire spesso il commit, in quanto il commit le fornisce un backup off-site del suo lavoro e una registrazione di ogni commit.

Non può impegnare alcuna modifica senza un Riepilogo, ma la Descrizione è facoltativa.

Impegnarsi è molto semplice. L'applicazione desktop ha già svolto tutto il lavoro di identificazione di ciò che deve essere impegnato. Inserisca un titolo per le modifiche efacoltativamenteinserisca una descrizione più lunga, esegua il commit della modifica premendo il pulsante "commit to (branch)". Assicurati di effettuare i tuoi commit sul tuo ramo di lavoro, non sul tuo ramo principale. Effettuare commit frequenti ti fornisce una cronologia dettagliata delle modifiche che stai apportando, rispetto a un singolo commit con tutto una volta che hai finito. Nota che c'è un limite di lunghezza per il Sommario. Tuttavia, se superi il limite, il tuo messaggio si riverserà automaticamente nella Descrizione più lunga. Puoi vedere che succede quando il testo nel campo Sommario diventa grigio.

Appena effettui il commit, GitHub desktop dovrebbe mostrare un avviso grande che indica che non ci sono modifiche locali. Dovrebbe anche suggerire di inviare il tuo commit all'origine. In alternativa, potrebbe suggerire di "Pubblicare il ramo". Comunque, effettuando le modifiche, queste vengono ancora solo memorizzate sul tuo computer. Per ottenere tali modifiche su GitHub, devi inviarle all'origine, il repository che viene memorizzato online. Basta premere il pulsante "Invia all'origine" o "Pubblica il ramo". In alternativa, ogni volta che l'origine e il clone sono obsoleti, dovrebbe esserci un pulsante molto male etichettato in alto a destra che ha un numero e una freccia. Ciò dovrebbe, tra le altre cose, sincronizzare tutto tra il tuo repository e il clone, quindi potresti inviare quello al posto di quello. In cima allo strumento desktop, la voce di menu a discesa "Repository - Push" farà anche il lavoro.

Continua a modificare e fare commit finché le tue modifiche non sono complete e hai il codice pronto da testare e debuggare pronto per essere inviato al resto di Roll20. Ora sei pronto per richiedere agli amministratori del sito di Roll20 di "pullare" le tue modifiche nel repository ufficiale di Roll20.


Crea una richiesta di pull

Come suggerisce il nome, unpullè l'opposto di un push. Invece di una copia del repository che invia commit all'originale, l'originale chiede commit dalla copia.

Sulla pagina web del tuo repository, c'è un pulsante verde che dice "Confronta, rivedi, crea una richiesta di pull" quando ci passi sopra con il mouse. Questo pulsante ti porterà a una pagina in cui puoi creare una richiesta di pull. Se ci sono differenze tra il tuo repository ("head") e la versione del repository di Roll20 ("base"), verranno visualizzate qui. (Nota che puoi modificare cosa usare come sia l'head che la base cliccando sul vicino pulsante "Modifica".) Poiché le tue modifiche sono tutte nel tuo ramo di lavoro, non nel tuo ramo principale, vuoi che la tua richiesta di pull provenga dal tuo ramo di lavoro.

Poiché non ha i permessi di collaboratore sul repository di Roll20, non può eseguire lei stesso l'azione di pull, ma può richiedere aqualcun altro di eseguire il pull. Premi il grande pulsante verde denominato "Crea pull request" e verrà aperta una pull request sul repository di base. Le persone autorizzate a farlo (ossia gli sviluppatori di Roll20) possono esaminare la pull request così come il contenuto delle modifiche proposte, e quindi unire la richiesta nel repository ufficiale.

Per chiarezza, includi il nome del foglio per il quale hai apportato modifiche nella pull request, ad esempio. "[Dungeondivers 3rd Edition] fixed broken Might roll".

Per l'invio delle schede dei personaggi, si ricordi di includeresheet.jsone un'immagine di anteprima - controlli il readmeper maggiori informazioni. Per l'invio di script API, si ricordi di includerescript.json- controlli il readmeper maggiori informazioni. Supponendo che tutto sia corretto, il suo foglio o script dovrebbe essere aggiunto al fileapproved.yamled essere disponibile per tutti gli utenti!

Una volta alla settimana, Roll20 elabora tutte le richieste di fogli disponibili. Quando ciò accade, riceverai una email da GitHub. Questa email ti informerà se è stato lasciato un commento sulla tua richiesta riguardante un problema riscontrato con la tua presentazione OPPURE se il tuo foglio è stato unito come previsto e la tua richiesta è stata chiusa (perché è stata completata con successo).

Apportare modifiche alla tua richiesta di PULL

Se crei una richiesta di pull e poi commetti & push alcune modifiche aggiuntive al tuo repository/branch prima che la richiesta di pull venga unita, queste nuove modifiche verranno automaticamente aggiornate/incluse nella richiesta di pull originale; non è necessario fare una seconda richiesta di pull.

Pull request button.png


Pulizia

NON eliminare nessun branch finché tutte le richieste di pull da quel branch non sono completate e chiuse. In realtà non c'è mai fretta di eliminare un branch. Non danneggiano nulla purché tu ricordi di utilizzare ogni branch una sola volta.

Il software GitHub ti consiglierà di unire il tuo branch di nuovo in master. Questo è un passaggio necessario con altri flussi di lavoro, ma non nel Flusso di lavoro di Forking che stiamo usando. Invece, ti consigliamo di sincronizzare il tuo fork con il roll20 originale come primo passaggio nella preparazione per il tuo prossimo aggiornamento. Questo porterà gli aggiornamenti che hai appena fatto (così come eventuali modifiche fatte da altre persone) nel tuo fork.

Pertanto non è necessario alcun ripulitura da fare.


Ulteriori informazioni


Tutorial Youtube su Git e Github per i poeti

Video di 10-20 minuti per persone non tecniche che insegnano le basi di Git e Github, mostrando come lavorare con Github nel browser, ma anche con un'introduzione all'uso della linea di comando. È stato realizzato nel 2016, ma da una rapida occhiata non sembra essere datato (marzo 2019).


Git e Github per Poeti (oltre i concetti di base)

 
Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 10 su 13