Skip to content

Developer workflow

Jump to bottom
Matthew Taylor edited this page Jun 3, 2013 · 10 revisions

WORKING DRAFT

This tutorial explains Numenta's branching strategy and developer workflow for making and submitting contributions to the project.

This tutorial assumes you already have Git installed and working. Also be sure to sign our Contributor License, if you haven't already, before you contribute.

Branch Information

Development happens on two main branches. The following describes what each of these code branches represents:

  • master: (Read-only) Do not commit directly into this branch. All code in this branch has built and fully passed all unit tests and should be stable.

  • dev-master : Current working branches containing code that has not been through the Continuous Integration (CI) process. Developers check their changes in to this integration branch for the automated testing system to validate. Once they are validated, the code is merged into master.

Git Pull Request Model

We follow a simplified version of Vincent Driessen's git branching model. The main difference between our model and Vincent's is that we don't currently deal with release branches. These will potentially be added in the future as this project matures.

Initial Setup (for non-committers)

  1. Fork the project on GitHub (http://www.github.com/numenta/nupic).
  2. Clone the fork to your local environment for development.

Note: If you are already a committer, you don't have to fork the repository. You can simply create a remote feature branch on the main repo.

Do Good Stuff

  1. Create a feature branch off master to house atomic code changes.
  2. Satisfy the contribution requirements (see NuPIC Contribution Standards).
  3. Push changes to your fork (or remote branch).
  4. Submit a pull request from your fork or branch to the dev-master branch for review.
  5. Incorporate community feedback.
  6. Push changes to your fork/branch -- the pull request will automatically update.
  7. Repeat if necessary.

All changes should continue to be made on the feature branch; that way the pull request you submit will automatically update to include them. Make sure to keep the feature branch updated with the latest changes from master, so that they don't diverge during your development process.

Happy Path

If a contributor adheres to our contribution standards, all tests should pass locally. The reviewer should attempt to run tests on a local checkout of the feature branch if suspicious of the changes. If everything passes, documentation is provided, and there are no breaking changes, the reviewer will approve the pull request and merge into the dev-master branch for the Continuous Integration (CI) system to take over and run the entire automated test suite.

Our git branching model, happy path

Once the CI process builds and runs all tests (and they pass!), the changes on dev-master will be merged into the master branch.

Not So Happy Path

Sometimes things don't go well! Failure is always a possibility. We want to keep the master branch green at all times, so if any of portions of the continuous integration process fails, we can't merge. At this point, the CI system sends out notifications to anyone involved in the feature branch, including contributors and reviewers.

git branch model when the CI process fails

At this point, the main priority for everyone is to fix the problem and get dev-master back into a green state.

Important Tips

  • Always work from a feature branch. Since all code submissions will be through a Pull Request, feature branches isolate changes from one submission to another.
  • Always start your new branch from the branch you want to submit to: git checkout -b myfeature dev-master
  • Remember to submit your Pull Request to the dev-master branch and not master.
Clone this wiki locally