Sporadic Godot Tutorials - Contributing on GitHub

I'll go ahead and assume that if you're watching this video, you are aware that the Godot Engine is open source via the MIT license and the source code is able to be downloaded and edited by anyone, and sometimes people will submit pieces of code to be merged with the main engine codebase, which is how most open source software works.

So basically, if you want to submit one of those little pieces of code (known as pull requests), you're gonna have to learn a little bit about how GitHub works. I'll outline basically what you have to do for any GitHub project right here:

• "Fork" the repository.

You can think of this like a "fork in the road" type thing, where half the path leads on to your version of the codebase and the other path is the "official" version of the codebase.

• Create a "branch" in your fork

So your repository already has a few branches. Branches are different versions of the codebase, but on a smaller scale than a fork. You will pretty much always have a "master" branch in your fork, which will usually hold the exact same code as the main repository earlier. This master branch is basically designed as a reference point for the other branches.

For example, you might create a branch called "fix-this-weird-bug". This would be based on your master branch, so most of the code would be exactly the same, but then you'd make changes to the code that fixes whatever weird bug you're chasing. Then you could create another branch that says "add-spiderman" also based on your master branch, then add spiderman... whatever that means. This means that you can create multiple concurrent changes to your codebase, so that when you create a pull request the maintainers of the original repository aren't forced to either take ALL of the changes you've made, or none of them. They can pick and choose which branch to merge.

• Create a "pull request" from your new branch to the master branch of the original repository(not your fork, the real one!)

Basically, a pull request is a request for one of your branches to be merged with a branch in the original repo. This is pretty much the final step, it'll show up on the original repo's "pull request" list and the maintainers of the repo can either merge the pull request or close it without merging.

Phew, so that's that in a nutshell. I don't know if that made much sense to you, but I hope it did. So let's get on to the specifics for the Godot Engine.

In order to fork the repository, go to its GitHub page, and click the button that says "Fork" in the top-right corner.

 This will create a repository called "godot" under your own account name, rather than that of "godotengine". Next, we have to clone the repo. I don't know how to do this with the official GitHub desktop client, but I do know that it's very simple on the command line or with a third party client with GitKraken, so I'll be using the command line for this.

Go to your profile and click the godot repository. Find the "Clone or Download" button, click it and copy the URL.

Now, go to a terminal and type "git clone" and then the URL that you just copied. This will hopefully clone your entire forked repository into a folder named "godot".

Now, you can move into this folder by using cd or something and type "git remote add upstream https://github.com/godotengine/godot" which will make your master branch point to the mainline godot repository. This means that your master branch will keep up to date with the changes that are happening in the real repo, as long as you regularly uses the"git fetch upstream" command.

Next, go back to the original Godot Engine's repository page and look for something to do under "Issues". If you've already got something to do then just continue, but that Issues tab is the tab where all the bug reports go, so it's a nice place to hang out.

Now, create a new branch. You can do this by going to your command line, cd-ing into the folder you cloned the repo into and typing "git checkout -b fix-some-bug-thing". This creates a new branch on your fork named "fix-some-bug-thing", and puts you into that branch. You can check to see a list of existing branches by typing "git branch", and hopefully it'd give you a list of potential branches, one of them being named "fix-some-bug-thing" with a * just before it to indicate that it's selected.

So, now you can get to work doing some of that amazing programming that you're known for. Done? Good! For the sake of completeness, I'll note at this point that you can compile the engine by typing "scons platform=[windows, osx, x11]". In addition, you can add a "-j4" tag to use 4 threads to compile. This will usually make it a little faster to compile, but your computer may slow down as a result because all the processing power is being used.

If you're like me and you don't have gcc-5 installed(I could install it, but I'm afraid that I'll break something) then you can append "use_llvm=yes" to the end of your scons command, and it'll use clang instead of gcc-5, which is usually easier to install.

Anyway, if you want more on that topic there are a lot of very informative doc pages which give you more information than I'm going to here, so in the mean time let's get back to GitHub.

Once you've made all the changes that you want to make to your branch on GitHub, you can run the command "git commit -m "i fixed a bug thing, woo!"" and then "git push origin master", except make the commit message a bit more informative than that to make things easier for the other contributors. Also, if you've made multiple commits and things are looking a bit messy, you might want to rebase. I don't understand this one as much as I do the others, so I'm just going to copy and paste what Remi, one of the project maintainers, asked me to do on GitHub the last time I made a huge mess.

git pull --rebase upstream master
git push --force origin master

Once you've done this, you can go to the original Godot GitHub page, and find the "New Pull Request" button along the top. Press the "compare across forks" button just under the big "Compare changes" header, and make sure that things look pretty much like this:

It should also give you a list of changes below that box. Once you're ready, you can create the pull request with a nice snappy title and description, then it's just a matter of waiting for one of the maintainers to pop in and talk to you about your pull request- even if you've made a horrible mess, they've always been very considerate and patient in my experience. 

Also, make sure that everything is formatted properly, because if it isn't then Travis CI will throw some errors at you. Just hang around for a few minutes with the Travis CI in mind and before you know it, it'll be yelling at you and telling you to put spaces somewhere or remove spaces somewhere else.

If all of that seems a bit daunting, then you're right on track. It's taken me years to even slightly understand Git and even now, I'm not entirely sure about all of it. However, there are other ways to contribute to Godot! You can write documentation if you're not a programmer(you'll still have to use Git though), you can donate on Patreon, or any of the other things it lists on the doc pag about "Ways to contribute".

I think that one of the best ways to contribute is in fact to just make games with the engine. The more examples and support threads there are out there, the higher number of people will feel more comfortable with adopting the Godot Engine as their primary engine and the healthier the eco system will become. Again, this is listed on the actual doc page so I should probably stop talking right now before I straight-up plagiarize that whole website.

Thanks for reading, and I hope that this has been helpful. I'm aware that a lot of this already exists online in several places, but I think that it might be helpful to have a slightly less scary or daunting tutorial somewhere on the Internet, plus I mean tutorials get me a hell of a lot of clicks, am I just gonna ignore that? Yeah, I don't think so, you better believe that I'm MILKING that, baby!