openFrameworks git workflow

Introduction

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 openFrameworks/develop by contributors. They only contain work on a certain feature or bug fix, respectively. They don't live in the openframeworks repository. Completed work is merged back into openFrameworks/develop from the newly created branch with a pull request.

• Integrators, when possible, merge with the --no-ff option (or using the Merge button in the github web interface) to create a new commit even in fast-forward merges, to improve the information in the git history about the newly merged branch. After merging, confirm that any connected and solved issues are closed in the issue tracker.

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

How to contribute

If you want to contribute to OF, you typically do the following:

• Make sure that the develop branch in your fork is in sync with openFrameworks/develop. Branch off from current develop, choosing a fitting name for the new branch (e.g. feature-newEventModel).

• Work on your contribution in the new branch. Test your changes to make sure they work and fix the bug.

• If your work fixes a certain bug which is in the issue tracker, be sure to include fixes <issueNr> or closes <issueNr> in one of the (probably the final) commit messages. Then said issue will be auto-closed as soon as the commit is merged. Sadly, including this in the PR description alone does NOT work.

• 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 your new work will apply cleanly onto openFrameworks/develop.

• Then, from the new branch, send a pull request against openFrameworks/develop (not master, which is the default setting). Describe the bug (e.g. by referring to an existing issue using the GH #<issuenr> syntax), and indicate if you have tested the changes, and any other relevant details.

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

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 oF git cheat sheet: A small list of helpful git commands put together by oF developers.

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.