Skip to content

Latest commit

 

History

History
127 lines (91 loc) · 4.46 KB

GITFLOW.rst

File metadata and controls

127 lines (91 loc) · 4.46 KB
Raw

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.

Guidelines

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 rationale 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 git@github.com:USERNAME/PROJECTNAME.git

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:

cd PROJECTNAME
git remote add upstream https://github.com/ORGANIZATION/PROJECTNAME.git

# 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: Remember to branch off master/main. Note: you have only one pull request per branch:

    git checkout -b DESCRIPTIVE_BRANCH_NAME

  • Hack away: Make your changes. Note: please only address one issue per branch/pull request.

  • Test: Test as you go.

  • Commit: Commit as you go, provide a biref descrption:

    git add FILENAME.EXT
git commit -m "BRIEF DESCRIPTION"

  • 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:

git push origin DESCRIPTIVE_BRANCH_NAME

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.