Guide to GitKraken
About
So you want to contribute some features to our server, but don't know where to start? Don't want to deal with the abomination that is GitTortoise? Don't have any idea what a pull request even is?
This is my guide to using GitKraken, a git interface, in order to make a pull request on the Yogstation repository. It is aimed at complete beginners. I also think GitKraken is much easier to use than some of the alternatives, although every git interface can do the same things the others can.
Make sure you open the spoilers, as they contain images to help guide you.
Terminology
| Repo | Short for Repository. Contains all the Yogstation code, assets, commits, and other info. This is what you see at https://github.com/yogstation13/Yogstation |
|---|---|
| Fork | A copy of the repo that belongs to you. It is not synced with the main repo, so you can make changes to it without affecting the main repo, and vice versa. |
| Branch | An independent version of your fork that you can work on without affecting your other branches. It is a way to group your commits. |
| Commit | A change to the repo that is submitted by someone. This change can be as small as single space you decided to add, or a complete re-write of multiple files. |
| Diff | Short for Difference. The difference in a repo before and after a commit is made. It shows you each change line-by-line. |
| PR | Short for Pull Request. This a request you make to the Yogstation repo to merge changes from one of your branches into the master branch on Yogstation. |
| Merge | When a branch is merged into a repo, all of the commits on that branch are applied to the repo. |
| Origin | In this guide, this refers to your fork of the Yogstation repo. |
| Upstream | In this guide, this refers to the master Yogstation repo at https://github.com/yogstation13/Yogstation |
Setting up the Yogstation repository in GitKraken
First, download and install GitKraken from https://www.gitkraken.com/ The download page contains a tutorial video that you can watch, if you want to be more familiar with GitKraken. It contains a lot of Git-specific terms. Don't worry if these don't make sense to you.
Log in to GitKraken. Click "Sign in with GitHub", and use your GitHub account. If you don't have one, make one at https://github.com/
| Spoiler | ||
|---|---|---|
| ||
Next, log into GitHub and go to the Yogstation repo at https://github.com/yogstation13/Yogstation. Click the Fork button on the top right. This will create your very own fork of the Yogstation repo, where you can work in peace.
| Spoiler | ||
|---|---|---|
| ||
Back to GitKraken. Click the folder icon in the top left, and go to the Clone tab. Under the "Clone with URL" option, you will have two options to fill out:
| Spoiler | ||
|---|---|---|
| ||
Where to clone to: Simply browse to a location on your computer where you will keep the Yogstation files(~1GB). This is where you will do all your changes. I've put it in Documents.
URL: this is where GitKraken will download the files from. Copy the link from your fork of the Yogstation repo on GitHub. The link should look like this: https://github.com/YourGithubUsername/Yogstation-TG
Don't copy the link to the yogstation13/Yogstation-TG repo- it MUST be your fork at YourGithubUsername/Yogstation-TG.
Finally, a third option will appear, called Full Path. Leave this one as it is.
Click the green button, and the Yogstation repo will start downloading. This is a ~1gb folder, so this could take a while.
| Spoiler | ||
|---|---|---|
| ||
Bake some cookies while you wait. This step is essential and you will get merge conflicts if it's not done properly.
Finally, when you're done, click the Open Now button at the top of the screen. This will open the main interface!
| Spoiler | ||
|---|---|---|
| ||
To be brief: The bar at the top of the page contains commands and lets you navigate to different repositories you may download(like Yogbot!). The left panel contains a list of your branches, remotes, pull requests on the repo, and a few other things you won't need. The diagram in the middle graphs a map of every commit on the repo and those you make, listed from the top(newest) to the bottom(oldest) Drag the edge of the panel outwards to see the branches like in the picture. Finally, the panel on the right contains information about the commits you click on. You can see the diff for every file changed in a commit here.
| Spoiler | ||
|---|---|---|
| ||
One last thing. Your GitKraken client is connected to your fork, but you also need to connect it to the actual Yogstation reposity so that you can send your changes there. To do that, you use remotes. Let's add the remote to the Yogstation repo. Hover over the remotes tab, press the green plus button, and then select the yogstation13/Yogstation-TG remote from the drop down list. It should be the first one, but you can type it in if it doesn't appear. Then, give it the name upstream. You can call it what you want, but I will refer to it as upstream in this guide, because it is the repo where code comes from- updates get pulled from it to you, and you need to push your own changes to it. Hit Add Remote and you're ready to go.
| Spoiler | ||
|---|---|---|
| ||
Now that we're set up, let's get to the fun part!
Making your changes
Note: once you're done making your first PR, you can return to this guide and start from here to make another PR.
A little talk about branches: I hope you've thought of what you actually want to do. First thing to do is to make a new branch on your fork. This is important because you should never make changes to the default(master) branch of your fork. It should remain as a clean slate. For every PR you make, make a new branch. This way, each of your individual projects have their own branch. A commit you make to one branch will not affect the other branches, so you can work on multiple projects at once.
To make a new branch, right click on master under the Local tab in the left panel. This is a list of all your branches. Click Create branch here. Pick a name for your project. In this guide I'll be adding new mugs to the station.
| Spoiler | ||
|---|---|---|
| ||
To switch between which branches you are currently working on, just double click on that branch. Make sure you have "checked out" your new branch by double clicking on it. You can make sure it's checked out because of the green check mark beside the branch name.
Remember, never commit changes to your master branch! You can work on any branch as much as you want, as long as you commit the changes to the proper branch.
Now, your files. Remember where you told GitKraken to clone your fork of the Yogstation repo? Go there now.
Here you have the entirety of the code and assets that compile into the game you play on the Yogstation server. You'll notice that this is an exact copy of your fork on the GitHub website. It won't be for long though- the folder isn't synced to the Yogstation repo, so if someone else makes a change to it it won't show up on your computer. We'll get back to this later, don't worry.
| Spoiler | ||
|---|---|---|
| ||
Go wild! Make all the changes to to code in here. This is a guide on how to make a pull request, not the features it contains. So I won't tell you how to code, make sprites, or map changes. I might make a spriting guide at a later date, but for now you're better off perusing the other guides, asking for help in #development-public on Discord, or figuring out the code yourself.
Here are the changes I am making now, briefly:
I added two new mug sprites to icons/obj/drink.dmi: I copied the britcup sprite, which was already present, and modified it to make new mugs.
| Spoiler | ||
|---|---|---|
| ||
I added the code for these two mugs in code/modules/food_and_drinks/drinks/drinks.dm: I simply modified the code from drinks/britcup into drinks/mug.
| Spoiler | ||
|---|---|---|
| ||
I added the two mugs to the station map in _maps/map_files/Yogstation/yogstation.2.1.3.dmm: If you make map changes, remember to read the instructions at https://tgstation13.org/wiki/Map_Merger before making your changes. This is crucial!
| Spoiler | ||
|---|---|---|
| ||
Now, save your changes. Back to GitKraken! You might notice a new node that has appeared at the top of the branch diagram. This is the WIP node. Click on it now.
| Spoiler | ||
|---|---|---|
| ||
On the right panel, you'll see a list of changes that you made in your commit, under Unstaged Files.
| Spoiler | ||
|---|---|---|
| ||
GitKraken has found every change you made to your fork's repo on your computer! Even if you change a single space in a single line of code, GitKraken will find that change. Just make sure you save your files. GitKraken will track changes even if it is not open, so you don't have to have the interface open while you do your work.
Now, click the green Stage all changes button, or pick each file you want to change individually. Staged files are the changes you are going to be submitting in commit, and then in your pull request. Once you've done that, they'll appear on the bottom of the right panel, under Staged Files.
| Spoiler | ||
|---|---|---|
| ||
Click on one of the files you've changed now! You'll see the diff of the file appear in the center, where the branch diagram was. Here you can see, line by line, every change that you made. Red lines are lines you removed or changed, and green lines are the lines you added or updated. You can even stage or unstage individual lines, by clicking on them.
| Spoiler | ||
|---|---|---|
| ||
GitKraken can even view the diff of a .dmi file! It will show a before/after view of the image. GitHub can't view .dmi files, so GitKraken is useful for checking changes that have been made to sprites.
| Spoiler | ||
|---|---|---|
| ||
Now that you've staged your changes, you're ready to make a commit. At the bottom of the right panel, you'll see the Commit Message section. Type a descriptive name for you commit, and a description if necessary. Be concise!
| Spoiler | ||
|---|---|---|
| ||
Make sure you're checked out on the new branch you created earlier, and click the green button! This will make your commit and add it to your branch. Note: selecting the Amend option will add whatever you changes you made to the last commit on that branch.
There you go! You have successfully made a commit to your branch. This is still only on your local computer, as indicated by the little computer icon.
| Spoiler | ||
|---|---|---|
| ||
Now, to get these changes onto GitHub, press the Push button on the command bar at the top of the screen. This will push the commit you made to GitHub. You need an internet connection to do this, obviously.
| Spoiler | ||
|---|---|---|
| ||
GitKraken will ask you what remote/branch you want to push to. Leave the remote at origin and and press submit. The branch is already typed in for you.
| Spoiler | ||
|---|---|---|
| ||
Origin refers to your fork of the Yogstation repo. Upstream refers to the actual master Yogstation repo. You want to make the changes to your fork, so always pick origin.
If you go to your fork on the GitHub website and go to your code, you'll see that your changes have been made! Make sure you're checking out the right branch.
| Spoiler | ||
|---|---|---|
| ||
I know it's tempting, but don't press the green button.
Okay, we're almost done! Make as many changes and commits on your branch as you want, and move to the next step when you're done! Make sure to test your code. If you're not sure how to do that, ask somebody on #development-public.
Submitting your pull request
Still with us? Good, because we're almost done. Go back to GitKraken.
Right click your new branch on the left panel or in the branch diagram. Click Start a pull request to upstream/ from origin/YourBranch.
| Spoiler | ||
|---|---|---|
| ||
A window will appear asking you to input information about your pull request. On the left, under From Repo and Branch, make sure you you've selected your fork, and your new branch, respectively. This is referring to the branch with the commits you just made. On the right, under To Repo and Branch, make sure you've selected yogstation13/Yogstation-TG and master. This is referring to the master Yogstation repo. Finally, click Edit on GitHub. This will open the GitHub website. You can put the information in GitKraken, but it's easier to do on the GitHub.
| Spoiler | ||
|---|---|---|
| ||
The GitHub website will open, and you'll be able to type in information about your pull request. All you need to worry about is your PR title, the description, and the changelog.
| Spoiler | ||
|---|---|---|
| ||
Write a descriptive title for your PR. Go into more detail in your description, explaining what you changed and why. If your changes could raise any issues or debate, make sure you discuss some of that here. Add relevant images if you made map or sprite changes.
| Spoiler | ||
|---|---|---|
| ||
Now you have to write your changelog. This is what players see when they click the changelog button on the server. It has a specific format you need to respect. The correct format is already present in the PR description, you just need to edit it with the changes you made. You can also add a specific contributor name after the first :cl: for that to show up in the changelog. If you leave it blank, it will use your GitHub username. Note: Only make a changelog for changes the players can experience. For example, if you just clean up code or make performance changes, you don't need to add them to the changelog.
The prefix before each line in the changelog will add an icon to it. Here is a list of what prefixes you can use:
- bugfix
- wip
- tweak
- soundadd
- sounddel
- rscadd
- rscdel
- imageadd
- imagedel
- spellcheck
- experiment
For example, writing this in your pull request description:
| Spoiler | ||
|---|---|---|
| ||
Will look like this in the changelog:
| Spoiler | ||
|---|---|---|
| ||
A more detailed guide on how to write your changelog can be found at https://tgstation13.org/wiki/Guide_to_Changelogs.
Finally, press Create pull request and there you go- it's submitted! You can look at the pull request here at https://github.com/yogstation13/yogstation/pull/2680
| Spoiler | ||
|---|---|---|
| ||
Adding more commits to your PR
There can be two reasons for this: You either want to fix changes to your PR, or want to add to it after the fact. In either case, the process is the same.
You'll notice, after you submitted you PR, that a check will start taking place. This is the Travis CI check, which will build you code and look for errors. It will take a few minutes to complete.
| Spoiler | ||
|---|---|---|
| ||
If the check passes, you'll get a green check mark appear next to your latest commit. This means everything is good to go!
| Spoiler | ||
|---|---|---|
| ||
If the check fails, a red X will appear next to the commit instead, and you'll see the failed check at the bottom of your PR. This means that you will have to fix the change.
| Spoiler | ||
|---|---|---|
| ||
Adding more commits is easy!
- Make your fixes or edits on your computer.
- Go to GitKraken and check out the branch that you used in your PR.
- Stage the changes you made.
- Make your new commit.
- Click Push as the top of the screen.
| Spoiler | ||
|---|---|---|
| ||
Done! Your new commit will automatically appear on GitHub, and Travis CI will check your code again. Note: You can add as many commits to a branch as you want before pressing Push.
| Spoiler | ||
|---|---|---|
| ||
Help! I've got merge conflicts!
The bane of every contributor. Merge conflicts occur when a file that you changed in your pull request is changed on the Yogstation repo. Now the repo has two different options to pick from- does it use the updated file on the repo, or the changed file on your pull request? You'll be able to tell that you have merge conflicts if you see this on your pull request:
| Spoiler | ||
|---|---|---|
| ||
You won't get a notification for this, so make sure to check on your PRs from time to time!
Solving this can be very easy, but it can also be very difficult depending on the change. If you need help, make sure to ask on #development-public. You can do two things- either merge both changes into one file, or simply pick one of the two files to use.
How do you do this? Let's head to GitKraken. What we're going to do is merge the Yogstation master branch, with the new updates, onto our branch. This counts as a commit, so any updated files on the Yogstation master branch will be added to your branch. When you make the commit, GitKraken will then ask you to resolve each conflict one by one.
We need to fetch the changes from GitHub. This is like the opposite of a push- pushing sends info from your computer to GitHub, while a fetch sends info from GitHub to your computer.
Check out the branch you used in your PR. Click on the little arrow next to Pull, and click Fetch All.
| Spoiler | ||
|---|---|---|
| ||
Note: One of the Pull options has a green circle next to it by default. Don't press this, even if tempts you.
Once that's done, go to your Remotes in the left panel. Scroll down to where the Yogstation remote is. This remote is a little window into the Yogstation repo, where you can execute some commands that involve it. On my computer, the remote is called upstream.
| Spoiler | ||
|---|---|---|
| ||
Now, right click the master branch of the Yogstation remote. Select Merge remote/master into yourbranch. You will get a notice saying There are merge conflicts that need to be resolved. Click the new node at the top of the branch diagram.
| Spoiler | ||
|---|---|---|
| ||
In the right panel, click on a conflicting file. This will open the conflict resolver.
| Spoiler | ||
|---|---|---|
| ||
Now, as I said before, you can do one of two things: ...Either pick which file you want by selecting one of the two at the top of the screen.
| Spoiler | ||
|---|---|---|
| ||
...Or go into the diff below and select which changes to merge, line-by-line.
| Spoiler | ||
|---|---|---|
| ||
Once you've picked the right changes, look at the Output on the bottom to make sure it is correct.
| Spoiler | ||
|---|---|---|
| ||
Finally, click Save in the top right to resolve that conflict. Do the same for all other conflicting files.
If you have conflicts between images files, you won't be able to go in line-by-line, obviously. Just select which image you want to use. If neither image works, pick any of them and make a commit afterwards with the errors corrected.
If you have conflicts between map files, just merge the updated file from the Yogstation master branch, then make a commit afterwards where you re-add the edits you made.
Once every conflict is resolved, simply type a commit name and press Commit and Merge. As you can see, this is exactly the same as making a commit.
| Spoiler | ||
|---|---|---|
| ||
Note: Depending on how many changes were made to the Yogstation repo since you made your branch, you might have an absurd number of files to stage. Don't worry, this is just a result of every single updated file being added to your branch. Just make the commit.
Now, make any more commits you need, hit Push again and your changes will be sent to GitHub. Travis CI will make another check and everything should be good to go!
| Spoiler | ||
|---|---|---|
| ||
I fucked up and need to restart
This happens- maybe you followed a step wrong, and now everything is messed up and you have no idea how to fix it. Sometimes in these cases you just need to delete everything and try again. Even doing that can be difficult however, so here's how to get a clean slate.
Obviously, if you do this, you will lose all your work. Keep that in mind and back up what you want to keep.
Start by closing GitKraken, and navigate to C:\Users\[YourName]\AppData\Roaming\.gitkraken\profiles\[ID] on your computer. [ID] is a really long code with numbers and letters in it. Don't worry about it. Inside, find the file called localRepoCache and open it up with a text editor. Find the line that corresponds to your cloned repository, and simply delete it.
| Spoiler | ||
|---|---|---|
| ||
Now navigate to where your fork is cloned on your computer (it's the same location as is described in the line you just deleted) and delete that entire folder.
Next, go to GitHub, log in, and visit your fork. Head to the settings tab, and scroll all the way to the bottom, to the Danger Zone. Find the "Delete this repository" button, and use it. This deletes any work you've done, unless it has already been PRed to the origin(yogstation13/Yogstation-TG). This means that all your unfinished work will be gone forever.
| Spoiler | ||
|---|---|---|
| ||
Once you've done that, you now have a clean slate. Go ahead and re-do the steps in this guide, starting from creating your fork.
What makes a good PR?
- Don't put unrelated, independent changes in the same PR. Make two different PRs instead.
- Test your code! Make sure it works!
- Listen to feedback you get on your PR.
- Name your commits properly, detail what your changes are.
- Make a concise changelog.
- Make good features?
Once you've finished your PR, you simply need to wait until the next merge wave where a maintainer will approve it. This could take up to a week. Be sure to listen to any feedback you get on your PR- that way you'll have a better chance at having your features approved.
You can check the pull request I made in this guide at https://github.com/yogstation13/Yogstation/pull/2680
I hope you found this guide useful!
Contribution guides
| |
| General | Hosting a server, Setting up git, Guide to GitKraken, Downloading the source code, Guide to contributing to the game, Reporting issues, Game resources category, Guide to changelogs |
| Database (MySQL) | Setting up the database, MySQL |
| Coding | Understanding SS13 code, SS13 for experienced programmers, Text Formatting |
| Mapping | Guide to mapping, Room Structure, Map merger |
| Spriting | Guide to spriting |
| Wiki | Guide to contributing to the wiki, Wikicode, Styleguide |