Beginner's Guide to GitHub
From Roll20 Wiki
Submitting Character Sheets, making them translatable to other languages and API Scripts for use by the community requires familiarity with GitHub.com.
This document is a simple, bare-bone guide to get you from "What in the world is Git?" to "Everybody should use my brand new character sheet!" as quickly as possible, without trying to teach you all the intricacies the system is capable of. Git is version control software, but this guide will totally ignore how you can use it to track your changes, and focus solely upon moving your updates to the master Roll20 repositories. The "More Info" section contains links to guides for how Git/GitHub works that are general in nature.
Before doing anything on GitHub, you will have to setup your computer by creating a GitHub account and creating a Fork and a Clone. Each time you wish to have the official repository updated with your tested and released changes, you ought to go through the GitHub flow of Syncing, Branching, Commiting, request a Pull, and Deleting (or maybe Merging) your branch.
Contents |
What is Git/GitHub?
Git is a piece of software that you install locally on your computer which handles version control for you. GitHub is a hosting service for Git repositories. So they are not the same thing: Git is the tool, GitHub is the service for projects that use Git. Brief comparison
There are several different ways to use Git. Git is very powerful and in order to get the very most out of it, you need to learn how to use the command shell (see the "More Info" section at the bottom). However everything that this document is going to be walking you through can be done using only GitHub Desktop GUI (very good at keeping your computers hard drive synchronized with your repository - See "Clone your Repository" below) and the GitHub web tools both of which are simplified tools to use the underlying Git. xkcd comic.
One thing to understand is that there will be several different copies of your project files that are stored in different places in different ways. This Beginners guide to GitHub will assist you in moving your project changes (ether to character sheets, or API scripts) through the various necessary stages. For each step of the process it is helpful to keep in mind which of the copies are being used or updated.
- The main official Roll20 GitHub https://github.com/Roll20 repository has two folders roll20-character-sheets and roll20-api-scripts. These repositories reside upon the GitHub servers. You have no direct access to these but can request that your updates be incorporated. Once your changes make it into here they are "going live" and become part of the scripts and character sheets available to all users.
- You will "Fork" yourself your own personal copy of the main Roll20 repository. This repository will likely have an https: address such as "github.com/YourNameHere/roll20-api-scripts" This repository will also reside upon the GitHub servers, however you will have full control over this copy and can modify it without affecting anybody else.
- You will "Clone" your "Fork", which will cause all the folders and files in the repository to be copied to your local computer hard drive.
- You can "Branch" your fork, so that you can differentiate between what is in your Master branch and your working branch.
- All of this is separate from the version of the code that you actually have within Roll20. If you are going to be modifying character sheets then you need to tell Roll20 that you are using a Custom character sheet, and paste the same html and css into both roll20 and the files on your hard drive so they can be uploaded to your repository.
As stated above, when you want to modify an existing character sheet or API script (or make a new one), you will need to Shepherd your changes through these different repositories.
Setup GitHub
Create Your Account
In order to use GitHub, you need to have an account on their website. You can create a paid account or you can create a free account. Unless you plan to create a large number of projects which you don't want to share with the world, there is no reason to create a paid account: the only difference between the various pricing levels is the number of private repositories you're allowed to have. Everyone, including free accounts, gets to have an unlimited number of public repositories.
You will be dealing with the master Roll20 Repositories for roll20-character-sheets and/or roll20-api-scripts which are public repositories. You will also be creating a fork of these repositories, which might as well also be public, so for your Roll20 usages, a free account is all you need.
FORK the Official Roll20 Repository
A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
Forking is easily done using the GitHub web tools. Click the Fork button on the official repository located at https://github.com/Roll20/roll20-character-sheets or https://github.com/Roll20/roll20-api-scripts as appropriate. This will create a copy of that repository in your account, which you will have permission to make changes to as you please. You can fork the repository as many times as you want, but you only need to fork it once. This new repository will have an address identical to the original, except instead of being at root "Roll20" will have a root of your roll20 account name.
If you are working with another user on the same sheet or script, it may be a good idea to go into your new repository's settings and add them as a collaborator. The details of how to add a collaborator or work with a collaborator are beyond the scope of this tutorial, however.
If you are familiar with the Git version control system, you shouldn't need any other information to complete your character sheet submission. Everyone else, read on!
CLONE Your Repository
Cloning a repository also makes a copy, but a cloned repository is used as a working copy and is upon your local computers hard drive as normal folders and files. Git maintains a link – by default named "origin" – between the folders and the repository it was cloned from.
For the beginner Git user, It is strongly recommend downloading and installing either GitHub for Windows or GitHub for Mac as appropriate for your operating system. These will hereafter be referred to in this document as "GitHub Desktop" or "the desktop app". In addition to being a simple way to install and setup Git version control on your computer, the GitHub desktop applications make it easy to link to your GitHub user account. It will tell you whenever your clone (files on your computer) is out of date with your repository (your own repository on GitHub) and allow you to easily synchronize the two.
When you first run the GitHub application, it will prompt you to log in to your GitHub account. Then, click the large plus sign in the top left to Clone your repository.
When you clone the repository, you'll be prompted to select a location to put the files. Make sure you select a location that you can find easily, you'll need to know where it is! If you get a new computer, installing the GitHub desktop and Cloning your repository is the only step that needs to be repeated.
The desktop app also has the easiest interface for managing Branches. When you switch branches within the desktop application, it will add / remove / change files so that they match the last commit done from the branch you have switched to.
If you're not using the GitHub application, you can find the clone url for your repository on the page for your repo. GitHub offers both SSH and HTTPS clone urls, as well as a Subversion checkout url. The details of cloning your repo manually are beyond the scope of this guide, however.
GitHub Flow
The setup above only ever needs to be done once. The procedures below should be followed every time you want to submit an update to the master Roll20 repositories.
Sync your files with Roll20
If you make/update another sheet or API script in the future, you do not need to create another fork, nor do you need to clone your repository again. You will need to update your fork with master. Read the guide below on how to sync
First, you may wish to see if you need to Synchronize the project(s) you will be working on. If you have just forked and cloned your repository a few minutes ago, it is still in sync. But if you are coming back to your repository after many weeks or months, chances are that many of the character sheets or API scripts have been updated. There is a possibility that the one you wish to modify is among them. In that case you need to make sure that you are working with the very latest version. One easy check is to look at the files in the Roll20 repository, and see the last modification date. Another is to open the files there and run a "diff" utility upon them and your most recent version. Check to see if there are any Pull requests pending against the files you will be updating.
Another option is to just pull all updates from the master Roll20 repository. This will get all the updates that other people have done to the roll20 repositories since the last time you synchronized them (including a bunch of character sheets or API scripts that you may not care about). This link has Guide to sync your repository with Original.
When you are done with this, the files in the Roll20 master repository, your own repository, your hard drive, and your roll20 campaign should all be the same.
Make a Branch
Make a branch for every separate project (character sheet or API script) and for every separate update. For example if you are going to be updating two different API scripts at the same time, make a branch for each script. If a few weeks later you decide to make additional changes to the same script, make a new branch for the newer update. As a rule of thumb, make one new branch for every pull request.
The desktop app also has the easiest interface for managing Branches. On the menu at the top, just pick "Branch / New branch". When you switch branches within the desktop application (The 2nd line allows you to switch the repository you are working on, and switch the current branch), it will add / remove / change files on your hard drive so that they match the last commit done from the branch you have switched to.
See also the last step in this flow, Merging or Deleting your Branches.
COMMIT Your Changes and PUSH your commits
When you commit changes, you store a record of everything you changed as well as a human-readable description of what you've done.
Once you have a working copy of your repository cloned, you can make changes to it. This includes creating a new folder for your character sheet or API script and adding the source code to it, or making modifications to files already there.
Many people, when developing Roll20 scripts or character sheets, do all of the actual editing in a text editor (for example notepad++). You can simply open the "clone" files (the ones on your hard drive) in any text editor and make the changes in the editor. Whenever you wish to run the code on Roll20, hit ctrl/a and ctrl/c to select all the text and copy it to the clipboard. Then paste it into the Roll20 settings page. If additional changes are needed (for example debugging) it is often easiest to continually perform a cycle of edit, copy, test.
When you have the text editor save your changes, it will finally write your changes to the file you have been editing, and GitHub Desktop will detect that the file you edited has changed and display the name of the file that has changed in its left pane, and in the right display a summary of what it detects as being different between the current save and the last commit that was made. However these changes have only been detected, GitHub does not actually made any record of these changes until you commit them. The Git experts recommend commiting often, as commiting gives you an off-site backup of your work, and a record of each commit.
Commiting is very simple. The desktop app has already done all the work of identifying what needs to be commited. Enter a summary of the changes and optionally enter a longer description, commit the change by presing the "commit to (branch)" button. Make sure you make your commits to your working branch, not your master branch. Making frequent commits provides you with a detailed history of the changes you're making, as opposed to a single commit with everything once you're done. Note that there is a length limit to the Summary. However, if you exceed the limit, your message will automatically overflow into the longer Description. You can see this happening when text in the Summary field turns gray.
As soon as you make the commit, GitHub desktop should display a large notice that there are No Local Changes. It should also suggest that you push your commit to the origin. Committing your changes still only stores them on your computer. In order to get those changes onto GitHub, you need to push them up to your origin, the repository being stored online. Simply push the "Push Origin" button. Alternatively, at any time origin and clone are out of date there should be a very poorly labeled button in the upper right that has a number and an arrow on it. That should, among other nice things, sync everything, so you could push that instead.
Continue to edit and make commits until your changes are complete and you have tested and debugged code ready to be submitted for the rest of roll20 to enjoy. You are now ready to request that the roll20 site administrators "pull" your changes into the official roll20 master repository.
Create a PULL Request
As its name suggests, a pull is the opposite of a push. Instead of a copied repository sending commits to the original, the original asks for commits from the copy.
On the webpage for your repository, there is a green button which says "Compare, review, create a pull request" when you hover over it. This button will take you to a page where you can create a pull request. If there are any differences between your repository ("head") and Roll20's version of the repository ("base"), they'll be displayed here. (Note that you can change what to use as both the head and the base by clicking the nearby "Edit" button.) Since your changes are all in your working branch, not your master branch, you want your pull request to come from your working branch.
Because you don't have collaborator permissions on Roll20's repository, you can't perform the pull action yourself, but you can request someone else to perform the pull. Press the large green button labeled "Create pull request" and a pull request will be opened on the base repository.The people with permission to do so (ie, the Roll20 developers) can examine the pull request as well as the content of the changes proposed, and then merge the request into the official repository.
For clarity's sake, please include the name of the sheet you have made changes for in the pull request, eg. "[Dungeondivers 3rd Edition] fixed broken Might roll".
For character sheet submissions, remember to include sheet.json and a preview image – check the readme for more information.
For API script submissions, remember to include script.json – check the readme for more information.
Assuming everything is correct your sheet or script should get added to the approved.yaml file and be available to all users!
Once a week, Roll20 processes all available sheet requests. When this occurs, you'll receive an email from GitHub. This email will either let you know a comment was left on your request regarding an issue that was discovered with your submission OR if your sheet was merged as expected and your request was closed (because it was completed successfully).
Making changes to your PULL Request
If you create a pull request and then commit & push some additional changes to your repository/branch before the Pull Request is merged, those new changes will be automatically be updated/included in the original pull request; there is no need to make a second pull.
Deleting or Merging your branches
Do NOT delete any branch until all pull requests from that branch are completed and closed. Actually there is never any hurry to delete a branch. They don't hurt anything so long as you remember to only use each branch once. On the other hand, it also does not hurt to tidy them up once you are certain you are done with them.
Almost all of the official Git documentation says that what you should do is merge your branches into your own master, and then make your pull requests from your master. The advice I get specifically about roll20 says there are better results from submitting pull requests from your working branches, then synchronizing your master fork with the roll20 master. It would be nice if somebody wise and experienced gave us a definitive best practice.
More info
- Tips on how to use Github (Roll20 forum thread)
- Git -The simple guide (command line tool) by Roger Dudler
- GitHub Workflow (GitHub Desktop) 6/22/16
Git and Github for Poets Youtube Tutorial
10-20 min long videos for non-technical people that teaches the basics on Git and Github, showing how to work with Github in the browser, but also have an intro to using the command line. It's made in 2016 but doesn't seem to be dated on a quick look(March 2019)
- 1.1 Git/GitHub intro 14 min
- 1.2 Branches 12 min
- 1.3 Forks and Pull Requests 13 min
Git and Github for Poets (beyond basics)
- 1.4 GitHub Issues 12 min
- 1.10 Git Remotes 14 min
