Pull request workflow#

If you want to help contribute to the project directly, by either fixing a bug or implementing a feature, then you’ll need to create a pull request on the project’s GitHub repository. This page explains the steps needed to do exactly that!

Creating a fork#

The way to think about forks is by thinking about going down a side road on a fork in the road - you’ll be doing your own think on the side road (your “fork”) while the main road (the repository’s master branch) goes on. Eventually, the side road will join back in with the main road later on (the “merge”).

To create a fork of the Tabletop Club repository on GitHub, you can go to the GitHub repository and click on the Fork button on the top-right. You should now have your own copy of the repository at that point in time. You can then clone the repository to your computer with git clone.

In this cloned repository, origin will point to your forked repository, which will not automatically update with the original repository. To make sure you can get updates from the original repository, you can add the original as a remote repository with this command:

git remote add upstream https://github.com/drwhut/tabletop-club.git

Now, if you ever need to update the master branch on your local repository, you can run the following commands:

git checkout master
git pull upstream master

You can then update your fork on GitHub with these changes:

git push origin master

Downloading and compiling Godot#

Now that you have made a local copy of the fork on your computer, there’s one more step that’s needed to be able to play, edit, and test the game - you’ll need to download and compile the modified version of Godot the game runs on. You can follow the instructions in Compiling from the source code up until the section where you download the game (you already did that just!) to get Godot up and running.

Making changes#

Before you start making the changes you want to make, it is highly advised that you create a branch on the local repository for the bug/feature you’re going to solve:

git branch <branch_name>
git checkout <branch_name>

Now you can start working on the code! See Coding guidelines for guidelines as to how you should write your code.

Note

When you are done, you should commit your changes and push them to your fork with these commands:

git add .
git commit
git push -u origin <branch_name>

Creating a pull request#

Once you’ve made the changes you wanted to make, and you’ve thoroughly tested them, you can push them to the custom branch on your forked repository and create a pull request!

To start, go to the original GitHub repository and click Pull requests > New pull request. Make sure you are merging from your fork’s custom branch to drwhut/tabletop-club on the master branch. If GitHub is happy, then you can click Create pull request, and fill in the details for the pull request.

Note

If the pull request was to fix an issue, then please put the issue number in the pull request! For example, if the issue fixes issue number 69, then say in the pull request: This PR fixes #69.

Once you’re done filling in the PR, you can submit it!

Note

If we ask you to make changes to the pull request, you can do so by making the changes locally on your computer and pushing the commits to your fork’s custom branch. These new commits will appear automatically in the PR.

Resolving merge conflicts#

There is a chance that GitHub will not let us merge the pull request into the master branch because of a merge conflict between the master branch and the branch on your fork. In this case, you should take the following steps:

  1. Update the fork’s master branch so it is up-to-date with the original’s:

    git checkout master
git pull upstream master
git push origin master

  2. Merge the master branch on your local repository into your custom branch:

    git checkout <branch_name>
git merge master

    Note

    You can also use rebase here instead of merge, but we don’t mind whichever command you use. Use whichever one you’re most comfortable with!

    At this point you’ll get the same merge conflicts that stopped the pull request from being merged. You need to resolve them before continuing.

  3. Test that the changes you’ve made still work after the merge.

  4. Push the merge commit, plus any other commits you make, to your fork.

  5. Go back to the pull request on GitHub, and ensure that there are no merge merge conflicts.