Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
123 lines (87 sloc) 4.31 KB

Recommended Git Flow

All TurnKey source code is managed by git, and hosted on GitHub in one of the following organizations:

Not only is GitHub used to host the source code, but also to facilitate collaboration via forks and pull requests.

There are infinate ways to develop with git, but when teams and collaborators are involved it's recommended to follow some sort of flow and guidelines. The most widely acceptable flows are git-flow and GitHub flow.


TurnKey related development is loosly based on the GitHub flow, and follows these guidelines:

  • Anything in the master branch is deployable - builds successfully and is tested to work.
  • When working on something new, whether it be a bugfix or new feature, create a descriptively named branch off of master. Each new branch should address just one issue (i.e. create a separate branch from master for each issue).
  • Commit to that branch locally and regularly. Source code should be documented and rational for changes included in commits.
  • When you need feedback or help, or you think the branch is ready for merging, open a pull request.
  • After someone else has reviewed and signed off on the changes, the project maintainer or a core developer will perform the merge in the official repository.
  • Once it is merged and pushed to master, the project should be rebuilt and released immediately.

Walk through

As described above, GitHub is used to facilitate collaboration, so the first thing to do is create a GitHub account and add your SSH public key if you haven't already done so.

Fork and clone the source

Next, fork the project you want to hack on:

  • Log into GitHub, and browse to the projects repository.
  • Click the fork button.

That's it. You've successfully forked the project repository, but so far it only exists on GitHub.

To be able to work on the project you'll need to clone it:

git clone

So far so good. When a repository is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repository it was forked from.

To keep track of the original repository, you need to add another remote, we'll call it upstream:

git remote add upstream

# Fetch any new changes to the original repository
git fetch upstream

# Merge any changes fetched into your working branch
git merge upstream/master

Make your changes

  • Create a branch: Note that you have only one pull request per branch:

    git checkout -b DESCRIPTIVE_BRANCH_NAME
  • Hack away: Make your changes, test and commit as you go. Remember please only address one issue per branch/pull request

  • Test: Perform final testing.

Push changes and submit a Pull Request

Now that you're finished hacking and all changes are committed, you need to push them to your GitHub repository:


Last thing to do is send a pull request so the maintainer or one of the core developers can review, sign off, and perform the merge in the official repository.

Hooray! You did it.

If for some reason the maintainer or one of the core developers has a problem with your change, they won't want to merge until fixed.

The good news is that whenever you commit and push more changes to that branch of your code, they will be included in that original pull request until it is closed.

You can’t perform that action at this time.