Anfängerleitfaden für GitHub

Dieses Dokument ist ein einfacher, grundlegender Leitfaden, der dich von "Was ist Git eigentlich?" zu "Jeder sollte meinen brandneuen Charakterbogen verwenden!" so schnell wie möglich bringt, ohne dir alle Feinheiten des Systems beibringen zu wollen. Git ist eine Versionskontrollsoftware, aber dieser Leitfaden wird völlig ignorieren, wie du sie verwenden kannst, um deine Änderungen nachzuverfolgen, und sich ausschließlich darauf konzentrieren, deine Aktualisierungen in die Haupt-Roll20-Repositorys zu übertragen. Im Abschnitt "Weitere Informationen" findest du Links zu allgemeinen Anleitungen zu Git/GitHub.


Was ist Git/GitHub?

Git ist eine Software, die du lokal auf deinem Computer installierst und die die Versionskontrolle für dich übernimmt. GitHub ist ein Hosting-Service für Git Repositories. Also sind sie nicht dasselbe: Git ist das Werkzeug, GitHub ist der Service für Projekte, die Git verwenden. Kurzer Vergleich.

Es gibt verschiedene Möglichkeiten, Git zu verwenden. Git ist sehr leistungsstark, aber um das Beste daraus zu machen, muss man lernen, wie man die Befehlszeile verwendet (xkcd-Comic). Der Abschnitt "Weitere Informationen" am Ende bietet zusätzliche Informationen zur Befehlszeile für Interessierte. Allerdings kann alles, was in diesem Dokument erläutert wird, nur mit der GitHub Desktop-Benutzeroberfläche (die sehr gut ist, um die Festplatte Ihres Computers mit Ihrem Repository zu synchronisieren - siehe "Repository klonen" unten) und den GitHub-Webtools durchgeführt werden. Beide sind vereinfachte Werkzeuge zur Verwendung von Git.


GitHub einrichten.

Erstelle dein Konto.

Um GitHub zu nutzen, benötigst du ein Konto auf ihrer Website. Du kannst ein kostenpflichtiges Konto erstellen oder ein kostenloses Konto erstellen. Es gibt keinen Grund, ein kostenpflichtiges Konto zu erstellen, es sei denn, du planst, eine große Anzahl von Projekten zu erstellen, die du nicht mit der Welt teilen möchtest. Der einzige Unterschied zwischen den verschiedenen Preiskategorien besteht in der Anzahl der privaten Repositories, die du haben darfst. Jeder, auch kostenlose Konten, kann eine unbegrenzte Anzahl öffentlicher Repositories haben.

Sie werden mit den Master-Roll20-Repositories für Roll20-Character-Blätter und/oder Roll20-API-Skripte umgehen, die öffentliche Repositories sind. Sie werden auch eine Kopie dieser Repositories erstellen, die auch öffentlich sein kann. Für Ihre Roll20-Verwendung ist ein kostenloses Konto alles, was Sie brauchen.


Gabeln Sie das offizielle Roll20-Repository

EinForkist eine Kopie eines Repositorys. Durch das Forken eines Repositories können Sie frei mit Änderungen experimentieren, ohne das Originalprojekt zu beeinflussen.
Roll20-Character-Blätter" ist das Charakterblätter-Repository. Gabeln Sie "Roll20-API-Skripte" für API-Skripte.

Das Forken erfolgt problemlos mit den GitHub-Webtools. Klicke auf den Knopf Fork im offiziellen Repository, das sich aufhttps://github.com/Roll20/roll20-character-sheetsoderhttps://github.com/Roll20/roll20-api-scriptsbefindet, je nachdem. Dadurch wird eine Kopie dieses Repositorys in deinem Konto erstellt, auf das du Berechtigungen hast, Änderungen vorzunehmen, wie du möchtest. Dukannst das Repository so oft faken, wie du willst, aber dumusst es nur einmal faken. Dieses neue Repository hat eine Adresse, die identisch mit dem Original ist, außer dass es anstelle von "Roll20" einen Ursprungsnamen deines Roll20-Kontos hat.

Wenn du mit einem anderen Benutzer an demselben Sheet oder Skript arbeitest, kann es eine gute Idee sein, in die Einstellungen deines neuen Repositorys zu gehen und ihn als Mitarbeiter hinzuzufügen. Wie man einen Mitarbeiter hinzufügt oder mit einem Mitarbeiter zusammenarbeitet, liegt außerhalb des Rahmens dieses Tutorials.

Wenn du mit dem Git-Versionssystem vertraut bist, solltest du keine weiteren Informationen benötigen, um deine Charakterbogeneinreichung abzuschließen. Jeder andere, lies weiter!


KLONE dein Repository

Klone ein Repository, macht auch eine Kopie, aber ein geklontes Repository wird als Arbeitskopie verwendet und befindet sich auf der Festplatte deines lokalen Computers als normale Ordner und Dateien. Git behält eine Verbindung - standardmäßig mit dem Namen "origin" - zwischen den Ordnern und dem Repository, von dem es geklont wurde.
Die Liste wird alle Repositories auf deinem Konto einschließen

Für den Git-Anfänger wird dringend empfohlen, entwederGitHub für Windows oder GitHub für Mac entsprechend deinem Betriebssystem herunterzuladen und zu installieren. Diese werden in diesem Dokument nachfolgend als "GitHub Desktop" oder "die Desktop-App" bezeichnet. Die GitHub-Desktop-Anwendungen erleichtern nicht nur die einfache Installation und Konfiguration der Git-Versionierung auf deinem Computer, sondern ermöglichen es dir auch, eine Verbindung zu deinem GitHub-Benutzerkonto herzustellen. Die App informiert dich, wann deine Dateien auf deinem Computer nicht auf dem neuesten Stand mit deinem Repository auf GitHub sind, und ermöglicht es dir, die beiden problemlos zu synchronisieren.

Wenn du die GitHub-Anwendung zum ersten Mal ausführst, werde dazu aufgefordert, dich in dein GitHub-Konto einzuloggen. Klicke dann auf das große Pluszeichen oben links, um dein Repository zu klonen. Wenn du das Repository klonst, wirst du aufgefordert, einen Speicherort für die Dateien auszuwählen. Stelle sicher, dass du einen Speicherort auswählst, den du leicht finden kannst. Du wirst wissen müssen, wo er sich befindet! Wenn du einen neuen Computer bekommst, ist das Installieren der GitHub Desktop-Anwendung und das Klonen deines Repositories der einzige Schritt, der wiederholt werden muss.

Die Desktop-App hat auch die einfachste Benutzeroberfläche für die Verwaltung von Branches. Wenn Sie innerhalb der Desktop-App zwischen Branches wechseln, werden Dateien hinzugefügt / entfernt / geändert, um mit dem letzten Commit des gewählten Branches übereinzustimmen.

Wenn Sie die GitHub-Anwendung nicht verwenden, finden Sie die Klone-URL für Ihr Repository auf der Seite für Ihr Repo. GitHub bietet sowohl SSH- als auch HTTPS-Klone-URLs sowie eine Subversion-Checkout-URL. Die Details zum manuellen Klonen Ihres Repos sind über den Rahmen dieses Leitfadens hinaus. 


GitHub Forking Workflow

Die oben genannte Einrichtung wird nur einmal durchgeführt. Im folgenden Abschnitt werden die Verfahren beschrieben, die empfohlen werden, wenn Sie ein Update an Roll20 übermitteln möchten.


Synchronisieren Sie Ihre Dateien mit Roll20

Wenn Sie gerade erst vor wenigen Minuten Ihr Repository geforkt und geklont haben, ist es noch synchron. Aber wenn Sie nach Wochen oder Monaten zu Ihrem Repository zurückkehren, wurden einige der Charakterbögen oder API-Skripte aktualisiert. Es besteht die Möglichkeit, dass derjenige, den Sie ändern möchten, darunter ist. In diesem Fall musst du sicherstellen, dass du mit den allerneuesten Versionen der Dateien arbeitest, die du ändern wirst. Du musstnichtein weiteres Fork erstellen, noch musst du dein Repository erneut klonen. Du musst deinen Fork mit dem Master aktualisieren. Lies die unten verlinkte Anleitung, wie du synchronisierst

Anstatt eine Synchronisierung durchzuführen, ob sie erforderlich ist oder nicht, könntest du zuerst überprüfen, ob du die Projekte, an denen du arbeiten wirst, synchronisieren musst. Eine einfache Überprüfung besteht darin, sich die Dateien im Roll20-Repository anzusehen und das letzte Änderungsdatum zu überprüfen. Eine weitere Möglichkeit besteht darin, die Dateien dort zu öffnen und eine"diff"-Dienstprogramm ausführen zu lassen und deine aktuellste Version. Überprüfen Sie, ob es noch ausstehende Pull-Anfragen für die Dateien gibt, die Sie aktualisieren werden. Wenn die spezifischen Dateien, die Sie ändern möchten, seit dem letzten Synchronisieren unverändert sind, ist eine vollständige Synchronisierung optional.

Eine andere Möglichkeit besteht darin, alle Updates aus dem Roll20-Master-Repository abzurufen. Dies lädt alle Updates herunter, die andere Personen in den Roll20-Repositories seit dem letzten Synchronisieren vorgenommen haben (einschließlich einer Reihe von Charakterbögen oder API-Skripts, die Ihnen möglicherweise nicht wichtig sind). Dieser Link enthälteine Anleitung zum Synchronisieren deines Repositorys mit Original. Wenn du damit fertig bist, sollten die Dateien im Roll20-Master-Repository, deinem eigenen Repository und deiner Festplatte identisch sein. Stelle sicher, dass du auch deine Roll20-Kampagne aktualisierst. 


Mache einen Branch

Es wird empfohlen, für jedes separate Projekt (Charakterbogen oder API-Script) und für jedes separate Update einen neuen Branch zu erstellen. Wenn du beispielsweise gleichzeitig zwei unterschiedliche API-Scripts aktualisieren möchtest, erstelle für jedes Script einen Branch. Wenn du einige Wochen später entscheidest, zusätzliche Änderungen am selben Script vorzunehmen, erstelle einen neuen Branch für das neuere Update. Als Faustregel gilt: Erstelle für jede Pull-Anforderung einen neuen Branch.

Die Desktop-Anwendung verfügt auch über die benutzerfreundlichste Oberfläche zum Verwalten von Branches. Wählen Sie im Menü oben einfach "Branch / Neuer Branch" aus. Wenn du innerhalb der Desktop-Anwendung Branches wechselst (Die 2. Zeile ermöglicht das Umschalten des Repositorys, an dem du arbeitest, und das Umschalten des aktuellen Branches), werden Dateien auf deiner Festplatte hinzugefügt / entfernt / geändert, sodass sie mit dem letzten Commit übereinstimmen, der in dem von dir ausgewählten Branch gemacht wurde.

GitHub Compare.png


COMMIT Deine Änderungen und PUSH deine Commits

Wenn du Commit Änderungen vornimmst, speicherst du eine Aufzeichnung von allem, was du geändert hast, sowie eine für Menschen lesbare Beschreibung dessen, was du auf deinem lokalen Computer getan hast. 
Dann pushst dudeine Commits in dein Repository.

Sobald du eine funktionierende Kopie deines geklonten Repositories hast, kannst du Änderungen daran vornehmen. Dies umfasst das Erstellen eines neuen Ordners für deinen Charakterbogen oder API-Skript und das Hinzufügen des Quellcodes oder das Ändern bereits vorhandener Dateien.

Viele Leute führen bei der Entwicklung von Roll20-Skripten oder Charakterbögen alle eigentlichen Bearbeitungen in einem Texteditor (z.B. Notepad++) durch. Du kannst die Dateien auf deiner Festplatte (diejenigen, die im "Klonen"-Schritt erstellt wurden) einfach in jedem Texteditor öffnen und die Änderungen im Editor vornehmen. Wenn du den Code auf Roll20 ausführen möchtest, drücke Strg+A und Strg+C, um den gesamten Text auszuwählen und in die Zwischenablage zu kopieren. Füge es dann in das entsprechende Feld der Roll20-Kampagne ein. Wenn weitere Änderungen erforderlich sind (z. B. Debugging), ist es oft am einfachsten, eine Bearbeitungs-, Kopier-, Einfüge- und Testzyklus durchzuführen.

Wenn du den Texteditor anweist, deine Änderungen zu speichern, werden deine Änderungen endlich in die Datei geschrieben, die du bearbeitet hast. GitHub Desktop erkennt dann, dass sich die bearbeitete Datei geändert hat und zeigt den Namen der geänderten Datei im linken Bereich an. Im rechten Bereich wird eine Zusammenfassung dessen angezeigt, was zwischen dem aktuellen Speichern und dem letzten Commit, der gemacht wurde, als unterschiedlich erkannt wird. Allerdings wurden diese Änderungen nur erkannt, GitHub hat diese Änderungen noch nicht protokolliert, bis du sie committest. Die Git-Experten empfehlen häufiges Committing, da es dir eine externe Sicherung deiner Arbeit und einen Überblick über jeden Commit gibt.

Du kannst keine Änderung ohne Zusammenfassung committen, aber die Beschreibung ist optional

Committing ist sehr einfach. Die Desktop-App hat bereits die ganze Arbeit erledigt, um herauszufinden, was committet werden muss. Gib einen Titel für die Änderungen ein und gib optional eine ausführlichere Beschreibung ein, committe die Änderung, indem du den „Commit to (Branch)“-Button drückst. Stelle sicher, dass du deine Änderungen in deinem Arbeitszweig und nicht in deinem Masterzweig committest. Häufige Commits bieten dir eine detaillierte Historie der vorgenommenen Änderungen, im Gegensatz zu einem einzigen Commit mit allem, sobald du fertig bist. Beachte, dass es eine Längenbeschränkung für die Zusammenfassung gibt. Wenn du jedoch die Grenze überschreitest, wird deine Nachricht automatisch in die längere Beschreibung überlaufen. Du kannst erkennen, dass dies geschieht, wenn der Text im Zusammenfassungsfeld grau wird.

Sobald du den Commit durchgeführt hast, sollte GitHub Desktop eine große Meldung anzeigen, dass keine lokalen Änderungen vorhanden sind. Es sollte auch vorschlagen, dass du deinen Commit zum Ursprung pushen. Alternativ könnte es vorschlagen, dass du den Zweig "Veröffentlichen". Das Commiten deiner Änderungen speichert sie immer noch nur auf deinem Computer. Um diese Änderungen auf GitHub zu übernehmen, musst du sie auf dein Ursprung, das online gespeicherte Repository, hochladen. Drücke einfach den Button "Push Origin" oder "Publish Branch". Alternativ gibt es im oberen rechten Teil, auch wenn er sehr schlecht beschriftet ist, einen Button mit einer Zahl und einem Pfeil. Das sollte, unter anderem, alles zwischen deinem Repository und dem Klon synchronisieren, sodass du das stattdessen hochladen könntest. Oben im Werkzeug gibt es ebenfalls den Dropdown-Menüeintrag "Repository - Push", der auch die Aufgabe erledigt.

Bearbeite weiter und mache neue Commits, bis deine Änderungen abgeschlossen sind und du den Code getestet und debugged hast, der bereit ist, für den Rest von roll20 freigegeben zu werden. Du bist jetzt bereit, die Roll20-Administratoren aufzufordern, deine Änderungen in das offizielle Roll20-Hauptrepository zu "pullen".


Erstelle einen PULL Request

Wie der Name schon sagt, ist einpulldas Gegenteil eines push. Statt dass eine kopierte Repository Commits an das Original sendet, fragt das Original nach Commits von der Kopie.

Auf der Webseite deines Repositories gibt es einen grünen Button, der "Vergleichen, überprüfen, einen Pull-Request erstellen" sagt, wenn du darüber schwebst. Dieser Knopf führt dich zu einer Seite, auf der du einen Pull Request erstellen kannst. Wenn es Unterschiede zwischen deinem Repository ("head") und Roll20-Version des Repositorys ("base") gibt, werden sie hier angezeigt. (Beachte, dass du durch Klicken auf die nahegelegene "Bearbeiten"-Schaltfläche ändern kannst, was als "head" und "base" verwendet wird.) Da deine Änderungen alle in deinem Arbeitszweig und nicht in deinem Hauptzweig sind, möchtest du, dass dein Pull Request von deinem Arbeitszweig kommt.

Da du keine Mitwirkungsrechte im Roll20-Repository hast, kannst du die Pull-Aktion nicht selbst durchführen, aber du kannstjemand anderen bitten, den Pull durchzuführen. Drücke die große grüne Schaltfläche "Pull Request erstellen", und es wird ein Pull Request im Basis-Repository geöffnet.

Um der Klarheit willen, füge bitte den Namen des Sheets, für das du Änderungen vorgenommen hast, in den Pull Request ein. Zum Beispiel "[Dungeondivers 3rd Edition] fixed broken Might roll".

Für Charakterbogen-Einreichungen musst du unbedingt die Dateisheet.json und ein Vorschaubild hinzufügen – überprüfe die Dateireadme für weitere Informationen. Für API-Skript-Einreichungen musst du unbedingt die Dateiscript.json hinzufügen – überprüfe die Dateireadme für weitere Informationen. Wenn alles korrekt ist, wird dein Charakterbogen oder Skript der Dateiapproved.yaml hinzugefügt und für alle Benutzer verfügbar sein!

Einmal pro Woche bearbeitet Roll20 alle verfügbaren Anfragen für Charakterbögen. Wenn dies geschieht, erhältst du eine E-Mail von GitHub. Diese E-Mail informiert dich entweder darüber, dass zu deiner Anfrage ein Kommentar zu einem gefundenen Problem hinterlassen wurde oder dass dein Charakterbogen wie erwartet zusammengeführt und deine Anfrage geschlossen wurde (weil sie erfolgreich abgeschlossen wurde).

Änderungen an deinem PULL Request vornehmen

Wenn du einen Pull Request erstellst und dann & Änderungen an deinem Repository/Branch vornimmst, bevor der Pull Request zusammengeführt wird, werden diese neuen Änderungen automatisch in den ursprünglichen Pull Request aktualisiert/einbezogen. Es ist nicht erforderlich, einen zweiten Pull Request zu erstellen.

Pull-Anforderungs-Schaltfläche.png


Aufräumen

Lösche keine Branches, solange alle Pull-Anfragen von diesem Branch abgeschlossen und geschlossen sind. Eigentlich besteht nie eine Eile, einen Branch zu löschen. Sie schaden nichts, solange du dich daran erinnerst, jeden Branch nur einmal zu verwenden.

Die GitHub-Software empfiehlt, deinen Branch in den Haupt-Zweig zu mergen. Dies ist ein Schritt, der bei anderen Workflows erforderlich ist, aber nicht im Forking-Workflow, den wir verwenden. Stattdessen empfehlen wir, deine Fork mit dem Roll20-Original zu synchronisieren, als ersten Schritt zur Vorbereitung auf dein nächstes Update. Dadurch werden die Updates, die du gerade gemacht hast (sowie alle Änderungen, die andere Personen vorgenommen haben), in deine Fork übernommen.

Daher ist keine Bereinigung erforderlich.


Weitere Informationen


Git und Github für Dichter Youtube-Tutorial

10-20 Minuten lange Videos für nicht technische Personen, die die Grundlagen von Git und Github lehren, zeigen, wie man mit Github im Browser arbeitet, aber auch eine Einführung in die Verwendung der Kommandozeile haben. Es wurde 2016 erstellt, scheint aber auf den ersten Blick nicht veraltet zu sein (März 2019)


Git and Github for Poets (beyond basics)

 
War dieser Beitrag hilfreich?
10 von 13 fanden dies hilfreich