Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Beginner's Guide to GitHub"

From Roll20 Wiki

Jump to: navigation, search
(Beyond your first Pull Request)
m (link ceanup)
(30 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Submitting [[Character Sheets]], [[Character Sheet i18n|making them translatable to other languages]] and [[API:Script Index|API Scripts]] for use by the community requires familiarity with [https://github.com GitHub.com].
+
{{NavSheetDoc}}
 +
Submitting [[Character Sheets]], [[Character Sheet i18n|enabling translations for them]] and submitting [[API:Script Index|API Scripts]] to the community requires familiarity with {{repo| GitHub}}, and this is a guide to show the minimum needed to operate it. '''It's highly advisable to learn more than the minimum to spare yourself from headaches.''' See '''[[Beginner%27s_Guide_to_GitHub#Other_Guides|Other Guides]]''' for more.
  
The following 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. The "More Info" section contains links to more guides for how Git/GitHub works but are general in nature.
+
This document is a 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 and is underlying everything on GitHub, but this guide will ignore it, and focus on showing the steps how to send Roll20 your proposed Character Sheet or API updates.
  
In five steps, the process for submitting a character sheet is Fork, Clone, Commit, Push, and ''request'' a Pull.
+
The '''[[Short Git Guide]]''' is an alternative to this guide that instead of using GitHub Desktop for some parts of the process, uses directly the [https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html Git Command Line Interface(CLI)] to perform most steps, while still performing the final step of sending Roll20 the update through GitHub in the browser.
 +
 
 +
The [[Beginner's_Guide_to_GitHub#Other_Guides |Other Guides]]-section contains more guides/resources for how Git/GitHub works that are more general in nature, and not necessarily tailor-made for Roll20-related things.
 +
[[File:GitHub.png|thumb|left|500px|The {{repo|Roll20/roll20-character-sheets Roll20 Character Sheet repository}} on GitHub. ]]
  
 
== What is Git/GitHub? ==
 
== What is Git/GitHub? ==
'''Git''' is a revision control system, a tool to manage your source code history.
+
'''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.
 
'''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'''. The GitHub web tools and downloadable GUI are tools to use the underlying Git. [https://jahya.net/blog/git-vs-github/ Brief comparison]
+
So they are not the same thing: '''Git''' is the tool, '''GitHub''' is the service for projects that use '''Git'''. [https://jahya.net/blog/git-vs-github/ Brief comparison]
 +
 
 +
See Also: '''[[Short_Git_Guide#Glossary|Git/GitHub Glossary]]'''
 +
 
 +
There are several different ways to use Git. Git is very powerful, but in order to get the very most out of it you need to learn how to use the command line interface (CLI) ([https://imgs.xkcd.com/comics/git.png xkcd comic]). The [[Beginner's_Guide_to_GitHub#Other_Guides |Other Guides]]-section has additional reading about the CLI for those interested. 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 [[Beginner's_Guide_to_GitHub#CLONE_Your_Repository|Clone your Repository]]) and the GitHub web tools both of which are simplified tools to use the underlying Git.
  
== Create Your Account ==
+
== Setup '''GitHub''' ==
 +
This is the steps & setup you only need to perform once to get you started with GitHub, and the [[#GitHub Branch-based Workflow, with Forks|GitHub Branch-based Workflow, with Forks]] will show how to do things if/when you submit changes beyond the first time.
 +
=== 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.
 
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.
  
GitHub recommends that you keep each repository under 1GB, and enforces a strict limit of 100MB per file. However, these limits are multiple orders of magnitude beyond what you should be working with for character sheets.
+
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 ==
+
=== '''FORK''' the Official Roll20 Repository ===
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">A ''fork'' is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea.</blockquote>
+
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">A ''fork'' is a copy/[https://docs.github.com/en/github/getting-started-with-github/github-glossary#clone clone] of another repository, with the difference that you are able to make direct changes to it. Forking a repository allows you to freely experiment with changes without affecting the original project.</blockquote>
 
<center>[[Image:Fork.png|thumb|800px|center|"roll20-character-sheets" is the Character Sheets repository. For API Scripts, fork "roll20-api-scripts".]]</center>
 
<center>[[Image:Fork.png|thumb|800px|center|"roll20-character-sheets" is the Character Sheets repository. For API Scripts, fork "roll20-api-scripts".]]</center>
  
Click the Fork button on the official repository located at [https://github.com/Roll20/roll20-character-sheets github.com/Roll20/roll20-character-sheets] or [https://github.com/Roll20/roll20-api-scripts github.com/Roll20/roll20-api-scripts] (as appropriate). This will create a copy of the repository on 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.
+
Forking is easily done using GitHub. Click the Fork button on the official repository located at [https://github.com/Roll20/roll20-character-sheets https://github.com/Roll20/roll20-character-sheets] or [https://github.com/Roll20/roll20-api-scripts 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 GitHub 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 are beyond the scope of this tutorial, however.
+
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!
+
If you are familiar with [https://git-scm.com/ Git](which GitHub is basicly just a web-version/hosting platform of), you shouldn't need any other information to complete your character sheet submission. Everyone else, read on!
  
== '''CLONE''' Your Repository ==
+
=== '''CLONE''' Your GitHub Repository to your Computer ===
 +
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">''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 &ndash; by default named "origin" &ndash; between the folders and the repository it was cloned from.</blockquote>
 
[[Image:Clone.png|thumb|250px|The list will include all repositories on your account]]
 
[[Image:Clone.png|thumb|250px|The list will include all repositories on your account]]
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">''Cloning'' a repository also makes a copy, but a cloned repository is used as a working copy, and it maintains a link &ndash; by default named "origin" &ndash; to the repository it was cloned from.</blockquote>
 
For the beginner Git user, I strongly recommend downloading and installing either [https://windows.github.com/ GitHub for Windows] or [https://mac.github.com/ GitHub for Mac] as appropriate for your operating system. In addition to being a simple way to install and setup Git version control on your computer, the GitHub applications make it easy to link to your GitHub user account.
 
  
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.
+
The reason why you forked Roll20's repository was because you don''t have direct rights to edit it, and the reason why you then clone your forked Roll20's repository instead of Roll20's repository, is so you can update/send things from your computer to your Github repository, from where you then send the Pull Requests to Roll20's 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!
+
For the beginner Git user, It is strongly recommend downloading and installing either [https://windows.github.com/ GitHub for Windows] or [https://mac.github.com/ GitHub for Mac]as appropriate for your operating system(Linux users need to directly use Git CLI or find an alternative for GitHub Desktop). 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 files on your computer are out of date with your 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.
 
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.
 
<br clear=all>
 
<br clear=all>
  
== '''COMMIT''' Your Changes ==
+
== GitHub Branch-based Workflow, with Forks==
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">When you ''commit'' changes, you store a record of everything you changed as well as a human-readable description of what you've done.</blockquote>
+
The previous section's action & setup is only needed to do once. The following section describes the procedures that is recommended to do each time you want to submit a new update to Roll20.
Once you have a working copy of your repository cloned, you can make changes to it. Most importantly, this includes creating a new folder for your character sheet or API script and adding the source code to it. When the files in your working copy are different from what has been committed to the repository, you'll see uncommitted changes listed in the GitHub application, as well as the difference between the recorded version and the current version.
+
 
 +
Alternatively, read the [[Short Git Guide]] for how you can use the Git CLI instead of GitHub Desktop for most things. The guide also have more clear method on how to keep your repository up to date with Roll20.
 +
 
 +
=== Update your Repository to be on par with Roll20's Repository ===
 +
[[File:GitHub Compare.png|thumb|right|500px]]
 +
If you have just forked/cloned your repository a few minutes ago, it is still in sync. But if you are coming back to your repository after more than a week, some of the character sheets or API scripts will have been updated in Roll20's Repository, but this isn't automatically done to your Repository.
 +
 
 +
While the updated things might not be related to the sheets you want to edit, it's still best to have your repository updated to be in sync with Roll20's. You do ''not'' need to create another fork, nor do you need to clone your repository again. You will need to update your Github repository's <code>master</code> branch(as well as any local copy copy of your repository on your computer) to be on par with Roll20 repository's <code>master</code> branch.
 +
 
 +
* '''{{repo|KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser a guide to sync your repository with Original}}'''
 +
 
 +
When you are done with this, the files in the Roll20 master repository, your own Github repository, and your cloned repository on your computer should all be the same.
 +
<br clear=all>
 +
 
 +
=== Make a '''Branch'''  ===
 +
''Recommended Read:'' '''[https://guides.github.com/introduction/flow/Understanding the GitHub's branch-based workflow]
 +
 
 +
It is recommended to make a new 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. '''Roll20 is likely to reject or delay Pull Request that makes changes to more than one sheet.'''
 +
 
 +
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.
 +
 
 +
=== '''COMMIT''' Your Changes and '''PUSH''' your commits ===
 +
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">When you ''commit'' changes, you store a record of everything you changed as well as a human-readable description of what you've done upon your local computer. <br>You then ''push'' your commits to your repository.</blockquote>
 +
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 files on your hard drive (the ones created in the 'clone' step) 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 correct Roll20 campaign field. If additional changes are needed (for example debugging) it is often easiest to continually perform a cycle of edit, copy, paste and test.
 +
 
 +
When you command the text editor to 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 pane 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.  
  
 
<center>[[File:Git Changed.png|thumb|1013px|center|You can't commit any change without a Summary, but the Description is optional]]</center>
 
<center>[[File:Git Changed.png|thumb|1013px|center|You can't commit any change without a Summary, but the Description is optional]]</center>
  
When you enter a summary of the changes and ''optionally'' enter a longer description, you can commit the change. Commit often! Making frequent commits can help you have 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.
+
Commiting is very simple. The desktop app has already done all the work of identifying what needs to be commited. Enter a title for 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.
  
== '''PUSH''' Your Commits ==
+
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. Alternatively it might suggest that you "Publish Branch". 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" or "Publish Branch" 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 between your repository and the clone, so you could push that instead. At the top of the desktop tool, the drop-down menu item "Repository - Push" will also get the job done.  
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">''Pushing'' sends all of your commits to the remote repository (by default, "origin"). While commit lets you record your changes, push lets you share your changes with others.</blockquote>
+
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.
+
  
Doing this within the GitHub application is simple. You'll notice in the top right corner a button labeled "Sync." This is called ''sync'' instead of ''push'' because it does more than just the push action. But all you need to know is that, among other things, the Sync button will push your changes.
+
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 ==
+
=== Create a '''PULL''' Request ===
 
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">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.</blockquote>
 
<blockquote style="border:1px solid #aaa;background:#ccc;padding:10px">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.</blockquote>
 
[[Image:Pull request button.png|thumb|511px]]
 
[[Image:Pull request button.png|thumb|511px]]
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 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.)
+
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.
 
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.
Line 60: Line 98:
 
'''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 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, assuming everything is correct (remember to include <code>sheet.json</code> and a preview image &ndash; check the [https://github.com/Roll20/roll20-character-sheets/blob/master/README.md readme] for more information), your sheet should get added to the <code>approved.yaml</code> file and be available to all users! API Script submissions do not currently have the same approval process as character sheets, so merging the pull request is all that's necessary.
+
For character sheet submissions, remember to include <code>sheet.json</code> and a preview image &ndash; check the {{repo|Roll20/roll20-character-sheets/blob/master/README.md Sheet Repository Readme}} for more information.
 +
For API script submissions, remember to include <code>script.json</code> &ndash; check the {{repo|Roll20/roll20-api-scripts/blob/master/README.md API repository Readme}} for more information.
 +
Assuming everything is correct your sheet or script should get added to the <code>approved.yaml</code> 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).
+
Once a week, Roll20 processes all available sheet requests. They usually start this process on Mondays after the weekly submit-deadline, and does their last changes on Tuesdays shortly before the weekly character sheet changes go live. 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(because it was completed successfully).
  
=== Making changes to your PULL Request ===
+
==== 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.
 
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.
  
== Beyond your first Pull Request ==
+
=== Cleanup ===
 +
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 at all. They don't hurt anything so long as you remember to only use each branch once.
 +
 
 +
The GitHub software will recommend that you Merge your Branch back into master, '''but do not perform this action'''. This is a step that is needed with other workflows, but not in the Forking Workflow which we are using. Instead, we recommend synchronizing your fork with the roll20 master branch as the first step in preparing for your next update. This will bring the updates you just did (as well as any changes anybody else has done) into your fork.
 +
 
 +
Therefore there is no cleanup that needs done.
  
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
+
==GitHub Gist==
 +
[[File:GitHub-Gist.png|thumb|550px|right|Example of a Gist, showing the code changes comparison for the latest version and the previous one.]] 
 +
[https://gist.github.com/ GitHub Gist] is a simple and smart way to share code with others, and is a lightweight option for sharing and  updating code for your character sheets with other without having to go into detail with how to work with repositories, branches, commits and other things.
  
1. Go to your fork
+
Using a Gist enables you to easily update the code and have access to a clear change history for the code, so you and other see clearly what have changed from previous versions of your gist. This history can be accessed in the "Revisions"-tab.
  
2. Click '''Compare'''
+
If you don't want to go through the trouble of forking the Roll20 repo or creating a repository just for sharing some code, Github Gist is a good alternative to other ways of sharing/hosting code many less regular programmer use such as [https://pastebin.com/ Pastebin], [https://www.dropbox.com/ Dropbox] or [https://drive.google.com Google Drive].
  
3. Submit and '''merge''' the pull request from master into your fork.  
+
* [https://docs.github.com/en/enterprise/2.13/user/articles/about-gists More about Gist]
 +
<br>
 +
<br>
 +
<br>
 +
== Other Guides ==
 +
Here are links to various other guide on how to use GitHub and/or Git which are made for understanding them in general, and aren't tailored to how they apply to Roll20.  
  
Always do this before you start new sheet work.
+
These guides will give you a better understanding of Git/GitHub itself which which lends itself to better understanding when you encounter trouble with Roll20 related things, as this [[Beginner's Guide to GitHub]](and the [[Short Git Guide]] to a lesser extent) skims over many things to only learn the bare essential to operate GitHub/Git in Roll20 context, but doesn't really teach how they actually work.
  
[[File:GitHub Compare.png|thumbnail]]
+
'''Understanding Git will make you understand GitHub better,''' and things related to it easier.
  
 +
Understanding Git/GitHub better is especially useful if you intend to collaborate/host own repositories for something like character sheet development for a specific sheet.
  
[https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser Guide to sync your repository with Original] (browser)
+
====General====
 +
Some general guides on how to use Git or GitHub
  
== More info ==
+
* {{forum|post/7282579/questions-about-github-advice-request-request-that-somebody-edit-beginners-guide-to-github-to-explain-a-bit-more Tips on how to use Github}}
* [https://app.roll20.net/forum/post/7282579/questions-about-github-advice-request-request-that-somebody-edit-beginners-guide-to-github-to-explain-a-bit-more Tips on how to use Github] (Roll20 forum thread)
+
  
* [https://guides.github.com/introduction/flow/ The GitHub Workflow(visualisation)]
+
* [https://guides.github.com/introduction/flow/ The GitHub Workflow(visualization)] (not the flow we use, but a good visualization) and [https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow Forking Workflow] (what we use)
  
 
* [https://rogerdudler.github.io/git-guide/ Git -The simple guide (command line tool)] by Roger Dudler
 
* [https://rogerdudler.github.io/git-guide/ Git -The simple guide (command line tool)] by Roger Dudler
Line 94: Line 147:
 
* [https://www.atlassian.com/git/tutorials Atlassian Git Tutorials]
 
* [https://www.atlassian.com/git/tutorials Atlassian Git Tutorials]
  
* [https://www.youtube.com/watch?v=ISkPyNkM2iY GitHub Workflow (GitHub Desktop)] 6/22/16
+
* {{yt|watch?v=ISkPyNkM2iY | GitHub Workflow (GitHub Desktop)}} 6/22/16
  
 
==== Git and Github for Poets Youtube Tutorial ====
 
==== 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)
+
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 was made in 2016, but seems to still be accurate when viewed(March 2019)
  
* [https://www.youtube.com/watch?v=BCQHnlnPusY&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV 1.1 Git/GitHub intro] 14 min
+
* {{yt|watch?v=BCQHnlnPusY&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV | 1.1 Git/GitHub intro}} 14 min
  
* [https://www.youtube.com/watch?v=oPpnCh7InLY&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=2 1.2 Branches] 12 min
+
* {{yt|watch?v=oPpnCh7InLY&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=2 | 1.2 Branches}} 12 min
  
* [https://www.youtube.com/watch?v=_NrSWLQsDL4&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=3 1.3 Forks and Pull Requests] 13 min
+
* {{yt|watch?v=_NrSWLQsDL4&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=3 | 1.3 Forks and Pull Requests}} 13 min
  
 
==== Git and Github for Poets (beyond basics) ====
 
==== Git and Github for Poets (beyond basics) ====
* [https://www.youtube.com/watch?v=WMykv2ZMyEQ&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=4 1.4 GitHub Issues] 12 min
+
* {{yt|watch?v=WMykv2ZMyEQ&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=4 | 1.4 GitHub Issues}} 12 min
  
* [https://www.youtube.com/watch?v=oK8EvVeVltE&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=5 1.5 Intro to command line] 9 min
+
* {{yt|watch?v=oK8EvVeVltE&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=5 | 1.5 Intro to command line}} 9 min
  
* [https://www.youtube.com/watch?v=yXT1ElMEkW8&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=6 1.6 Cloning Repo and Pull/Push] 22 min
+
* {{yt|watch?v=yXT1ElMEkW8&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=6 | 1.6 Cloning Repo and Pull/Push}} 22 min
  
* [https://www.youtube.com/watch?v=JtIX3HJKwfo&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=9 1.9 Resolve Merge Conflicts] 9 min
+
* {{yt|watch?v=JtIX3HJKwfo&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=9 | 1.9 Resolve Merge Conflicts}} 9 min
  
* [https://www.youtube.com/watch?v=lR_hYwCAaH4&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=10 1.10 Git Remotes] 14 min
+
* {{yt|watch?v=lR_hYwCAaH4&list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV&index=10 | 1.10 Git Remotes}} 14 min
  
* [https://www.youtube.com/watch?v=_sLgRBrZh6o Git Workflow (command line)] 7 min
+
* {{yt|watch?v=_sLgRBrZh6o | Git Workflow (command line)}} 7 min
  
 +
== See Also ==
 +
* [[Short Git Guide]] - A guide to use the command line version of Git to work on your computer with character sheets
 +
** [https://cli.github.com/ GitHub CLI beta] - Take GitHub to the command line, and create PRs in the CLI instead of through the GitHub website or the Desktop application.
 +
* [[Sheet Author Tips]] - Contains some advice related to GitHub/Git
 +
* [[Andreas Guide to Sheet Development]]
 +
* {{repo|Roll20/roll20-character-sheets Roll20 Character Sheet repository}}
 +
* {{repo|apps/pull Fork Update App}} - GitHub extension that automates the process of updating your fork. '''Warning:''' [[Sheet_Author_Tips#Install_Pull_to_GitHub|Read this]] before using it.
 +
<br />
 
[[Category:Guides]]
 
[[Category:Guides]]
 +
[[Category:Character Sheet Creation]]

Revision as of 21:41, 7 March 2021

Submitting Character Sheets, enabling translations for them and submitting API Scripts to the community requires familiarity with GitHub, and this is a guide to show the minimum needed to operate it. It's highly advisable to learn more than the minimum to spare yourself from headaches. See Other Guides for more.

This document is a 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 and is underlying everything on GitHub, but this guide will ignore it, and focus on showing the steps how to send Roll20 your proposed Character Sheet or API updates.

The Short Git Guide is an alternative to this guide that instead of using GitHub Desktop for some parts of the process, uses directly the Git Command Line Interface(CLI) to perform most steps, while still performing the final step of sending Roll20 the update through GitHub in the browser.

The Other Guides-section contains more guides/resources for how Git/GitHub works that are more general in nature, and not necessarily tailor-made for Roll20-related things.

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

See Also: Git/GitHub Glossary

There are several different ways to use Git. Git is very powerful, but in order to get the very most out of it you need to learn how to use the command line interface (CLI) (xkcd comic). The Other Guides-section has additional reading about the CLI for those interested. 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) and the GitHub web tools both of which are simplified tools to use the underlying Git.

Setup GitHub

This is the steps & setup you only need to perform once to get you started with GitHub, and the GitHub Branch-based Workflow, with Forks will show how to do things if/when you submit changes beyond the first time.

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/clone of another repository, with the difference that you are able to make direct changes to it. Forking a repository allows you to freely experiment with changes without affecting the original project.
"roll20-character-sheets" is the Character Sheets repository. For API Scripts, fork "roll20-api-scripts".

Forking is easily done using GitHub. 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 GitHub 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 Git(which GitHub is basicly just a web-version/hosting platform of), you shouldn't need any other information to complete your character sheet submission. Everyone else, read on!

CLONE Your GitHub Repository to your Computer

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.
The list will include all repositories on your account

The reason why you forked Roll20's repository was because you dont have direct rights to edit it, and the reason why you then clone your forked Roll20's repository instead of Roll20's repository, is so you can update/send things from your computer to your Github repository, from where you then send the Pull Requests to Roll20's repository.

For the beginner Git user, It is strongly recommend downloading and installing either GitHub for Windows or GitHub for Macas appropriate for your operating system(Linux users need to directly use Git CLI or find an alternative for GitHub Desktop). 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 files on your computer are out of date with your 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 Branch-based Workflow, with Forks

The previous section's action & setup is only needed to do once. The following section describes the procedures that is recommended to do each time you want to submit a new update to Roll20.

Alternatively, read the Short Git Guide for how you can use the Git CLI instead of GitHub Desktop for most things. The guide also have more clear method on how to keep your repository up to date with Roll20.

Update your Repository to be on par with Roll20's Repository

GitHub Compare.png

If you have just forked/cloned your repository a few minutes ago, it is still in sync. But if you are coming back to your repository after more than a week, some of the character sheets or API scripts will have been updated in Roll20's Repository, but this isn't automatically done to your Repository.

While the updated things might not be related to the sheets you want to edit, it's still best to have your repository updated to be in sync with Roll20's. You do not need to create another fork, nor do you need to clone your repository again. You will need to update your Github repository's master branch(as well as any local copy copy of your repository on your computer) to be on par with Roll20 repository's master branch.

When you are done with this, the files in the Roll20 master repository, your own Github repository, and your cloned repository on your computer should all be the same.

Make a Branch

Recommended Read: the GitHub's branch-based workflow

It is recommended to make a new 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. Roll20 is likely to reject or delay Pull Request that makes changes to more than one sheet.

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.

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 upon your local computer.
You then push your commits to your repository.

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 files on your hard drive (the ones created in the 'clone' step) 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 correct Roll20 campaign field. If additional changes are needed (for example debugging) it is often easiest to continually perform a cycle of edit, copy, paste and test.

When you command the text editor to 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 pane 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.

You can't commit any change without a Summary, but the Description is optional

Commiting is very simple. The desktop app has already done all the work of identifying what needs to be commited. Enter a title for 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. Alternatively it might suggest that you "Publish Branch". 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" or "Publish Branch" 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 between your repository and the clone, so you could push that instead. At the top of the desktop tool, the drop-down menu item "Repository - Push" will also get the job done.

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.
Pull request button.png

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 Sheet Repository Readme for more information. For API script submissions, remember to include script.json – check the API repository 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. They usually start this process on Mondays after the weekly submit-deadline, and does their last changes on Tuesdays shortly before the weekly character sheet changes go live. 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(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.

Cleanup

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 at all. They don't hurt anything so long as you remember to only use each branch once.

The GitHub software will recommend that you Merge your Branch back into master, but do not perform this action. This is a step that is needed with other workflows, but not in the Forking Workflow which we are using. Instead, we recommend synchronizing your fork with the roll20 master branch as the first step in preparing for your next update. This will bring the updates you just did (as well as any changes anybody else has done) into your fork.

Therefore there is no cleanup that needs done.

GitHub Gist

Example of a Gist, showing the code changes comparison for the latest version and the previous one.

GitHub Gist is a simple and smart way to share code with others, and is a lightweight option for sharing and updating code for your character sheets with other without having to go into detail with how to work with repositories, branches, commits and other things.

Using a Gist enables you to easily update the code and have access to a clear change history for the code, so you and other see clearly what have changed from previous versions of your gist. This history can be accessed in the "Revisions"-tab.

If you don't want to go through the trouble of forking the Roll20 repo or creating a repository just for sharing some code, Github Gist is a good alternative to other ways of sharing/hosting code many less regular programmer use such as Pastebin, Dropbox or Google Drive.




Other Guides

Here are links to various other guide on how to use GitHub and/or Git which are made for understanding them in general, and aren't tailored to how they apply to Roll20.

These guides will give you a better understanding of Git/GitHub itself which which lends itself to better understanding when you encounter trouble with Roll20 related things, as this Beginner's Guide to GitHub(and the Short Git Guide to a lesser extent) skims over many things to only learn the bare essential to operate GitHub/Git in Roll20 context, but doesn't really teach how they actually work.

Understanding Git will make you understand GitHub better, and things related to it easier.

Understanding Git/GitHub better is especially useful if you intend to collaborate/host own repositories for something like character sheet development for a specific sheet.

General

Some general guides on how to use Git or GitHub

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 was made in 2016, but seems to still be accurate when viewed(March 2019)

Git and Github for Poets (beyond basics)

See Also