Tutorial:Using a GitHub Project

From Spiral Framework
Jump to navigation Jump to search

So you've started work on a project recently, and you'd like to make it public, open source, and buildable. GitHub is a great place to host these projects, in particular because it's easy to set up, easy to maintain, as well as easy for Jenkins to build.

Prerequisite - GitHub account

GitHub does require an account to use, however accounts are free for public projects (And private projects won't build).

To get started, you'll need to register an account with GitHub. After you've gone through the whole confirmation jazz, you're ready to create a new repository over here.

In addition, we'll be using the desktop application for GitHub, as it allows for an easy way to change multiple files, as well as non text files.

Please note that your username, repository name, as well as all files that you add to the repository are completely public. Do not put sensitive information in any of them!


There's a few terms that we'll need to cover real quick.

A repository is, essentially, a project. It's where all your files are put, and you can add files as you go.

A branch is a separate copy of your project, to be able to edit bits individually. Branches are a good way to keep track of individual, smaller changes, before merging them into the master branch. However, we won't be covering them much in this tutorial, but if you'd like to learn more you can check out the guide here

The master branch is your primary copy of your project. This is the definitive version of your project, and the one that we'll build with. This will be the only branch we use, for simplicity, however you are able to use other branches as shown above if you'd like to.

Finally, a commit is a set of changes that you make to the project. When you commit a file, it gets added to the project, and any changes are applied.

Getting Started

The first step, if you haven't already, is to create a repository for your project. It's best to use the name of the mod here, but you can use anything you like. In addition, giving it a description serves to highlight what it is, without needing to open it up. Also, clicking "Initialise with README.md" allows you to provide more details about your mod, such as what it does, which games it supports, and so on.

After you've done this, you'll want to open up GitHub Desktop, and log in. After that's done, clone the repository you created (File > Clone Repository), and choose a space to store it on your computer.

Once that's done, congratulations! You've taken the first steps to having your project be public.

Making Changes

Now that we have our project, the next step is to make changes, and publish them.

You're able to structure the directory however you like, add any files you'd like, and GitHub will reflect them once you tell it to.

So, let's try that then! If you clicked "Initialise with README.md", you'll have one file - README.md. This is a file that is displayed when you visit the project on GitHub, and is useful for giving some information about your project. It's basic text with markdown, so you can use bold and italics here too.

This will be the first file we change, so let's edit it to just say "Hello, World!" for now.

Go to the directory that you cloned the repository into, and open the README.md file with any regular text editor. Add "Hello, World!", and save.

If you go back to GitHub Desktop, it should show that you've changed the file. It'll have a short blurb of changes to the right, as well as all the files you've changed to the left.

The only thing left to do now, is to write a short summary in the text field that says "Summary", and hit the big "Commit to master".

However, this won't reflect in the repository online. The reason for this, is that GitHub actually maintains a list of changes on your computer, as well as online. Pressing "Commit to master" changes the local repository, but not the one online.

To do that, you'll need to press "Push origin" at the top of the window, next to the two buttons that say "Current Repository" and "Current Branch". Once you've done that, it'll take a few moments to upload (or a while, depending on the file sizes and your upload speed). The big advantage of GitHub, is that you only need to upload files that you change, and it only uploads the changes themselves. So if you don't change any of the big files in your project, they won't be uploaded. Neat, huh?

Next Steps

You've done it! Your project is now stored on GitHub, which means people can look at it, and if you ever lose your files locally they're stored there for you to retrieve later.

Remember what I mentioned before, too? Jenkins is able to build your project into an installable mod.

To do that, you'll need to contact me (UnderMybrella) over Discord, over at "UnderMybrella#4076" or on the Discord server for SPIRAL here. If you give me your GitHub repository URL, I'll be able to set up the build for you.