Git Workflow

Git is a powerful and flexible tool, and there are many opinions on the "right" way to use it. One of the principles we follow is that everything on master should be deployable. In other words, every commit on the master branch should be a working version of Ohm that we would feel comfortable releasing. The commits should reflect a "logical" history of the project, not the literal history of every commit the developers made in their local repositories.

Here are some tips on how to use Git in a way that fits with our preferred workflow:

Using Feature Branches

When developing a bug fix or a new feature, it's a good idea to work on a branch dedicated to that topic. You can create a new feature branch like this:

git checkout -b my-feature-name master

This will create a new branch off master named my-feature-name.

Committing

As you develop the feature, it's a good idea to commit your changes frequently. You don't need to worry about the commit messages too much, as you can clean those up later. You may also want to use git commit --amend to keep all your changes in a single commit -- it's up to you.

Keeping Up-to-Date

To keep your feature branch up-to-date, you'll need to ensure that your local copy of master is up-to-date. If you have a checkout of the main Ohm repository, you can do this using git pull from your local master branch. If you have a fork of the repository, see the GitHub documentation on syncing a fork.

Once your local master branch is up-to-date, you can update your feature branch like this:

git rebase master

This will re-parent your commits onto the tip of the master branch. Some people don't like this, and prefer to use git merge instead. There are advantages and disadvantages to both approaches, but the rebase workflow makes it easier to maintain a clean history.

Preparing a Pull Request

When you're ready for feedback on your feature, it's time to submit a pull request. At this point, you should make sure that the commit history is clean. This means:

• Each commit should represent a logical unit of work
• There should be NO merge commits, or commits containing mistakes that are fixed in a later commit

Ideally, a pull request should have a single commit. If there are multiple commits, each one should represent a version that you would be comfortable releasing.

If you need to clean up your history for submitting your pull request, the easiest way is:

git rebase -i master

This allows you to combine (or "squash") commits, and edit your previous commit messages. This works best if you've been using git rebase to keep your feature branch up-to-date.

If you've been using git merge instead of git rebase, you can squash your changes by creating a new branch for your pull request (git checkout -b my-feature-name-pr master) and then merging your feature branch into it using git merge --squash my-feature-name.