openFrameworks git workflow

Intro

[bilderbuchi]: This page will detail the git branching workflow used in development of oF. This is currently a work-in-progress. :-)

This page documents the version control workflow followed by the openFrameworks community when dealing with the development of openFrameworks. If you want to contribute, and/or already have code or bug fixes you would like to see in the official repo, please follow these guidelines to make the life of the devs easier, minimize time needed for review, and ensure speedy and efficient incorporation of your improvements into oF.

The workflow

The git workflow for openFrameworks is based on this excellent article detailing a very good branching model. Read the article first, it's quite complete and nicely presented, no need to replicate everything here.

A quick overview of the most important points (included oF-specific customizations):

• The master branch contains the latest released, stable and tested version, and is only committed into on release of a new version.

• The develop branch is where development/integration of external contributions happen. If you submit pull requests, submit against develop.

• master and develop are the only permanent branches in the repository.

• feature-* and bugfix-* branches are branched off from current develop by contributors, and merge back into develop. They only contain work on a certain feature or bug fix, respectively. They don't live in the openframeworks repository.

• If you want to contribute to oF, you typically do the following:

• Branch of from current openFrameworks/develop, choosing a fitting name (e.g. feature-newEventModel).

• Work on your contribution.

• When you're satisfied with your work, and there were commits on openFrameworks/develop in the meantime, merge openframeworks/develop into your branch to ensure that it will apply cleanly onto openFrameworks/develop.

• Then send a pull request against openFrameworks/develop (not master).

• Collaborate with the devs on successfully integrating your work. If more work is needed, or there are open question about our changes, this will be discussed in the comment section of the pull request.

• Integrators, when possible, merge with the --no-ff option to create a new commit even in fast-forward merges, to improve the information in the git history about the newly merged branch.

• release-* branches support preparation of a new production release. They allow for last-minute dotting of i’s and crossing t’s, and minor bug-fixing.

• hotfix-* branches are created when a critical bug in a production version must be resolved immediately,

General git resources:

If you have just discovered git, or want to learn some tricks, there are a couple of resources you should look at (roughly in the order you should read them):

The github help page: Deals with basis usage, concepts and terms of git and github. Good to get a first idea.

gitref.org: Nice and concise reference of the essential functions of git. Takes about 30min to read through, you'll come out smarter at the end.

Pro Git: A book, also freely available on the homepage in html form. Deals with everything from git basics to advanced concepts.

The git man pages: The manual of git. Also available on your command line, but much more readable on the net. :D Bare-bones explanation of the details of command line git usage.

If you ever have a question about how to do things in git, it is often best to enter your question on Stack overflow. Most probably someone there has had your problem before. For example, How do I make git ignore mode changes?

There is also a great amount of articles, wiki pages, tutorials and blog posts about git, for example git for the lazy or Git Immersion.