Using GitHub

By this point, you should have already setup your development environment as per the instructions in the README. If you are only looking for instructions on the basic workflow of developing this project, the README should cover those needs. This page is meant to be a slightly more thorough overview of Git / GitHub and how we're using it in this project.

What is Git?

Put simply, Git is a version control software. Version control (a.k.a. source control) software has a couple primary goals:

1. Provide a way to share and maintain constantly-changing files between different users
2. Provide a backup and history of all changes ever made to a project

To accomplish these goals, Git allows you to take any folder and store it online. That online folder now becomes the One True Folder™. Now, the way Git supports collaboration is by having a copy of the One True Folder™ on every team member's computer. As opposed to team members changing files on their computer and sending them to each other, with Git you simply make changes on your own local copy of the project, and then send the changes to the One True Folder™. Git then stores a history of all the changes that have ever happened to the project and by who, and lets you update your local copy to the most recent version with a single click! That's it; that's Git!

* For the purposes of version control, and software development in general, the term "project" is always synonymous with "folder" - just like any other folder on your computer.

The Language of Git

Now that we understand the core idea behind Git, let's dive into how we can describe the different parts of this process in a more specific way.

• Repository (aka Repo): A repository is what we call a project that is using Git / stored online with Git.
• Remote / Origin: This is what we call the One True Folder™. It's the version of the project that is stored online!
• Local Repo: This what we call your own copy of the remote, stored on your personal computer. Everyone on the project has their own local copy that doesn't affect anyone else's version!
• Clone: When you clone a repository, it means you're creating a new local copy of the remote on your computer. For pre-existing projects, you always need to clone the repository to start working on it on your local computer!
• Commit: A commit is what we call a set of changes to a project. When you make a commit, you are creating a new version of the project. Commits are made to your local repo, and then sent to the Remote whenever you're ready for everyone else to receive your changes!
• Push: A push is what we call sending a commit from your local repo to the remote. This is how you update the remote!
• Pull: Conversely, a pull is what we call updating your local repo with the most recent version of the remote. This is how you get other people's changes!
• Conflict: A conflict occurs when you and another person on the project both try to push different, overlapping changes to the same file. When this happens, you will be given a list of options to take, such as manually merging the two sets of changes together!

We can interact with Git using a variety of tools. In this project, we use GitHub and GitHub Desktop (or your client of choice!).

GitHub is a website primarily used to view and interact with the repository remote directly; but as you can see, it offers a wide number of other related services as well, such as Issues (features/bugs list), Wikis (you are here), and Projects (team progress trackers), amongst many others!

GitHub Desktop on the other hand is a desktop app which will be your primary interface with Git. This lets you see all the changes you currently have in progress, and is where you will use commands such as Cloning, Committing, Pushing and Pulling. Advanced users may also prefer to type the commands directly into a terminal window!

Example: Adding some sprites to a project repo

Let's say I'm working on the RPG and I want to add some new sprites to the assets folder. This is my first time ever working on the project.

Since the RPG is an existing project, I must first clone the repository to my computer. That local copy is now just like any other folder on my computer.

To add my sprites, I simply paste them into the Assets folder of my local repo. GitHub Desktop now shows me a list of local in-progress changes, which are the sprites I've added. Satisfied with my changes, I use GitHub Desktop to write a commit message ("Add example sprites") and complete the commit. Desktop no longer shows any changes, but I can see a new commit in my local version history.

Since I have no other changes to do, I decide to push my commit to the remote. I press Push changes in GitHub Desktop, and after a few seconds, observe on the GitHub website that my sprites have been added to the remote repository, along with my commit showing as the most recent change!

Later, I come back to add more sprites, and find that my teammates have pushed some new code to the remote. GitHub Desktop shows me that I'm behind the most recent version on the remote by 2 commits, so I press Pull and observe the commits are added to my local computer's history.

Using Branches

Now that you've seen the fundamentals of Git and an example of how that might work in practice, there's one more critical area to understand: branches. Branches are the answer to a 3rd, very common problem that Git aims to solve: "What if we are developing multiple features at once?"

A branch is essentially a separate version of the project that can be developed in parallel with the main project version. Every repo has a "main" branch which you can think of like the "most recent stable version" (in the RPG project, this is the dev branch). Everything we've talked about so far has actually been with regards to this "main" branch - but in fact committing, pushing, pulling, etc., all work the same for every branch.

When you make a new branch, it starts as the most recent version of the branch that you branched off of; in other words, if you "branch off of dev" it means you're making a new version of the project starting from what's currently in the dev branch. In the RPG, we use branches to represent specific features, and we often have several of these in progress at a time (i.e. adding a new NPC, updating the dialogue system, or moving something in a level).

Let's dive into branches and define more specifically the different aspects of branching:

• Branch: A separate version of the project that allows for developing features independently from the rest of the project.
• Remote Branch: Much like commits, branches exist on both the local repo and remote. Anyone can pull the most recent version of a remote branch to their local machine in order to start making changes to it.
• Local Branch: A local branch is the local copy of a remote branch. You can commit, push and pull to this branch you usually would, in order to update its remote version.
• Publish: When you make a new local branch, it won't yet exist on the remote. Publishing tells the remote repo to create a new remote branch with all the current contents of your local branch!
• Checkout: This is what we call moving between branches. When you checkout a branch, your local project files will update to that branch's current version, and new commits will go into that branch's version history. You always have one local branch checked out at a time.
• Merge: Merging is what happens when you want a branch's changes to be integrated into another branch. In other words, when you're done with a feature, you would merge your branch back into the "main" branch; or vice versa, if you wanted to update your branch with the most recent changes in "main". This copies all the commits you made since creating your branch into the target branch!
• Pull Request (aka PR): A pull request is like a fancy merge. It creates a new page on GitHub with a summary of all the changes in your branch, so that other team members in your project can review it before it gets merged. Once it's reviewed, anyone can merge the PR directly from GitHub.

* Note: ALL feature branches in the RPG project must be submitted with a Pull Request, not merged directly!

Example: Adding an Enemy script in a new branch

This example will function exactly like the sprite example from before, except we'll make the changes in a new branch.

Let's say I've already cloned the repo to my computer. I now create a new local branch called enemy-script, and publish it to the remote. Now, everyone can see that branch on the remote and even copy it to their local computer to work on it if they want.

Next, I add my new script to the project files and commit my changes to the enemy-script branch. I then push my change to the remote enemy-script branch, and observe that everyone can now see my new commit in that branch.

Finally, happy with my feature, I create a pull request from enemy-script into dev. Another of my teammates looks over my code on GitHub, and approves my PR. I then submit the PR and my changes are automatically merged into dev.

Finished with the enemy-script branch, I delete it.

Conclusion

Now that you've gone through a summary of how GitHub works, don't forget to look through the README to see the specific contribution rules for this RPG project. Also, feel free to ask any questions about this on Discord!