GitKraken: Difference between revisions

From OoT Randomizer Wiki
(Started. First time GitKraken setup, cloning, forking, adding fork to GitKraken)
(No difference)

Revision as of 21:16, 5 October 2019

So, you want to start contributing to Ocarina of Time Item Randomizer. Maybe you know how to code in Python and want to improve something in the backend code or add a simple hack. Or perhaps you know some Assembly and want to contribute a whole new feature to add to the game. Even just a quick bug fix is always appreciated.

In order to contribute you will need to get familiar with Git, the version control system that the randomizer uses to organize and share its code. Git is normally a command line tool, but many GUIs also exist as a frontend that is more user-friendly, if a bit more limited than the actual Git tool. GitKraken is the GUI that many of the OoTR developers use and are familiar with so is the one you are most likely to get support for if you run into issues.


Run GitKrakenSetup.exe and it will automatically install itself and launch for the first time.

Sign in to GitKraken

GitKraken requires you register an account to use their software. Since you will be using GitHub to contribute to the randomizer anyway so sign up over there first then choose Sign in with GitHub. Doing so will launch a web browser with a page asking you to authorize GitKraken to access GitHub. Choose Continue authorization. Now sign in with your GitHub account if you are not already. You will then be brought to a page asking you if you want to authorize GitKraken to access your GitHub account on GitHub. Click `Allow` and GitKraken will now bring up the "Set Up Your Profile" screen.

Set up

There are a couple of things that need to be set up from here that you only need to do once. First, set up the GitKraken profile.

Here you select an avatar which only you will see, but will pull from Gravatar if you use an email address associated with an account which GitHub will also do. Ignore the "Profile Name" box, "Default Profile" is fine. Under "Name" it is traditional to use your full first and last name, but if you are not comfortable with that you can enter a nick name. The most important text box here is "Email" and it should be set to the same email address as your GitHub account. Now, click Save Changes and GitKraken will open proper.

Clone the main repository

With GitKraken set up go to File > Clone Repo and make sure "Clone with URL" is selected. Click on the Browse button next to the "Where to clone to" text box. By default GitKraken should choose the "Documents" folder. This is fine, you can click Select Folder to use it. If you are using Windows 7 you will get an error saying "You've selected a library. Please choose a folder instead." Click on the arrow next to the "Documents" library and choose "My Documents" then click Select Folder. In the URL box put the GitHub URL to the current main repository. At the time of writing the current main repo is https://github.com/TestRunnerSRL/OoT-Randomizer. Filling in the box will reveal a new "Full Path" text box. Leave this alone and click Clone the repo!.

GitKraken will now show a bar near the top of the window telling you that you cloned the repo. Click the Open Now button to open the repository in a tab. Congratulations, you now have a local copy of the randomizer code on your computer.

Forking the code

While you now have a copy of the code on your computer, you do not have permission to push code changes directly on to the existing repository. To actually make changes and upload them you need to create a copy of the main repository, called a Fork. Go to the main repository on GitHub and at the top right of the page you should see the Fork button. This will create a copy of the repository on your account which you have permission to modify.

Now, go back to GitKraken and hover over the REMOTE header on the left side of the screen. A "+" button should appear. Click that then in the new box that appears choose the "URL" option. Under "Name" put your username so that you can tell that it is your repository. Under "Pull URL" put the link to your repository. It will be similar to the following: https://github.com/username/OoT-Randomizer.git. Ensure you change username to your GitHub username. Click Add Remote to add your copy of the repository to GitKraken.

Congratulations, you are now prepared to submit contributions to the randomizer. You can follow these steps for any other Git or GitHub repositories you want to contribute to as well.