GitKraken

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.

• Click the Free Download button to download the GitKraken installer

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.

Profile setup 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

GitKraken with Ocarina of Time Item Randomizer open

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.

Managing Other Forks

Sometimes you will want to work off of branches on other forks of the Randomizer. You don't need a separate copy of the repository to do this. Git makes it very simple to switch between branches and tags of any other copy of the repository. Doesn't matter if it is on GitHub, some other website, or on a network share on another computer in your house. This section focuses on other forks on GitHub though, as that is where you'll find all of the OoT-Randomizer forks.

You follow the same directions from the previous forking the code section, but instead of your GitHub username in the "Name" and in the "Pull URL" using the same https://github.com/username/OoT-Randomizer.git URL you will change username to the GitHub username of the person who made the fork. You can then click Add Remote so that GitKraken will now know to look for more branches there. You can then use it much like the main repository is used in the following steps.

Contributing

Now that you have your own copy of the repository you can start changing code and submitting it to the main repo. The following steps go through the usual Git on GitHub workflow for contributions.

Create a local branch

Since repository maintainers will often change commits after they are submitted, usually to make the Git log history cleaner looking, you do not want to make changes directly on the main branch. You want to create a branch off of the main branch which will give you a clean workspace that you won't have to worry about figuring out how to update it when new changes are added to the main repository and you need to pull them down.

The main development branch for the randomizer is called Dev. Other repositories may use branches called develop or development as well, and some just use master as their main branch. When you start to add code you want to make a branch off of this main branch first. You should already have "Dev" selected under the "LOCAL" heading on the left side of the GitKraken screen. If it is not currently selected double-click it to select it. Now at the top of the screen is a button with a "Branch" label. Click this button then type a short description for what you intend your changes to be and press Enter. This will create a new branch and automatically check it out for you. Now under the "LOCAL" header you should see your new branch selected.

You may now make any changes to the code that you want. Code files are just normal text files, in this case using the .py, .c, and other file extensions instead of the .txt extension. They can be opened in any text editor that will open .txt files. Even Notepad, TextEdit, and gedit can open these files. The extension is only to help let you know that text within is expected to look a certain way. Visual Studio Code is such a text editor, and as it is cross-platform and used by many people in the community it is the one we recommend you use.

Commit and push your changes

Once you have made your changes, or are at a logical stopping point for part of them, you will want to commit your changes. If you go back to GitKraken you should now see a new entry at the very top of the Git log. It will have the text "// WIP" and next to it will be some icons. A "+" or "-" if you have added or removed any files, a pen if you have edited some, or a file icon if you have renamed one. Clicking on this entry should update the right side panel of GitKraken.

Under the "Unstaged Files" section you will see each file that you have modified in some way. You will want to ensure all of these are the changes you want to submit. If they are, simply click the "Stage all changes" button to move them to the "Staged Files" section. If there are some you don't want to submit, you can individually stage files with buttons that appear to the right when you hover over them with the mouse, or you can stage all the changes and remove individual ones the same way in the "Staged Files" area.

Once you have staged your changes move down to the "Commit Message" box. Put a short description of your changes in the "Summary" field. You shouldn't use more than 50-80 characters here. If you need to explain some things more clearly do so in the "Description" field below. Once you have entered a commit message you can click the Commit changes to {n} files button to commit your changes to your local branch.

With your changes committed locally you should now push them to your fork on GitHub. Click the "Push" button at the top of the screen and GitKraken will ask you to choose the remote branch you want to push to. Since this is a new branch you will want to create a new branch so just make sure your repository is highlighted in the dropdown box, then in the box next to it the name of your local branch should already be pre-filled. Click the Submit button and your changes should now be viewable on your GitHub repository page.

Making a pull request

You've now made your changes and pushed them to your fork. Next you need to make a pull request to the main repository to have your changes merged into the randomizer proper. Go to your OoT-Randomizer repository on GitHub. Near the middle left of the screen you should see a dropdown box with a "Branch: Dev" or "Branch: master" label. Click this then select the new branch you pushed with your changes. After the page reloads, right next to the dropdown box you will see a button labeled "New pull request." Click this button and a new page will load. The left side should already be pre-filled with the TestRunner repository and Dev branch, and the right side should already be pre-filled with your repository and the branch with your changes. If not, fix it now.

The pull request title will also be pre-filled with your "Summary" from your Git commit message, and the "Leave a comment" box will have your "Description" already filled in if you wrote one. You might want to change this to make it a bit clearer to people looking at the pull request page and the repository maintainer what your changes do. Once you are happy with what is here, click on the "Create pull request" button. If this is a larger change and you're still working on it but want feedback, you can also click the arrow next to this button and choose "Create draft pull request" instead.

Your pull request should now be created. You'll likely get comments from the developers and community members curious about different aspects of your changes, and you may get a request to change how something functions. To make changes to the pull request, just commit them to your existing local branch and push it to your fork branch again. This will automatically update the pull request.

Once your changes have been approved they will be merged into the main branch. At this point you can now delete your branch. For each new pull request you intend to make you should create a new branch based off the latest version of the main branch, and do these steps again.

Staying up-to-date

This is the easiest method to keep the Dev branch up-to-date. Ensure that "Dev" is selected under the "LOCAL" header. If it is not double-click the branch to check it out. Now click on the "Pull" button at the top of the screen. Yes, that is it.