Developer Workflow

Engineering NuPIC
, ,
1

This tutorial explains Numenta’s developer workflow for making and submitting contributions to the project. It is assumed you already have Git installed and working. You must sign our Contributor License before you contribute. See our video tutorial on contributing to NuPIC with git and Github.

Branch Information

NuPIC consists of two major repositories: nupic and nupic.core. All the information below applies to development on both repos.

We have only one branch: master. Development occurs on developer branches. If you are contributing to the project, you should fork the repository and create a “feature branch” for your work. Once you have it complete, create a pull request against the master branch.

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

All other branches are considered simply feature branches, which exist within forked repositories, not within the NuPIC repo itself. Only committers with push access may create branches on the NuPIC repository, so the normal flow for outside contributions involves a feature branch on a local fork.

We don’t currently deal with release branches. These will potentially be added in the future as this project matures.

GitHub Pull Request Model

Our model involves feature branches and pull requests. Once a pull request has been created against the master branch of NuPIC, the PR is validated by our tools server to confirm that it meets submission requirements. A Reviewer must confirm that PR is approved by the validation process before merging into master. Validation indications are clearly posted on the PR.

Initial Setup

  1. Fork the project on GitHub (GitHub - numenta/nupic-legacy: Numenta Platform for Intelligent Computing is an implementation of Hierarchical Temporal Memory (HTM), a theory of intelligence based strictly on the neuroscience of the neocortex.).
  2. Clone the fork to your local environment for development.

Do Good Stuff

Our developer workflow branching strategy

  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 master branch for review.
  5. Allow PR Validation to complete
  6. Incorporate community feedback.
  7. Push changes to your fork/branch – the pull request will automatically update and PR validation will run again.
  8. 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 (this will also cause the PR validation to fail).

Happy Path

If a contributor adheres to our contribution standards, the PR validation should run successfully. This validation includes:

  • Travis-CI build
  • Confirmation that author is on our list of contributors
  • Assurance the PR is in a merge-able state

During validation, the PR will be marked as pending:

A pull request pending successful validation
A pull request pending successful validation963×373 38.3 KB

After validation has passed, the PR will be ready to merge:

A pull request after successful validation
A pull request after successful validation960×380 38.3 KB

A Pull Request, Step by Step

Below is a detailed view of all the steps happening behind the scenes for a pull request.

Our developer workflow branching strategy (detailed)
Our developer workflow branching strategy (detailed)697×384 40.7 KB

Not So Happy Path

A pull request after failed validation
A pull request after failed validation974×383 38.1 KB

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 validation process described above fails, we can’t merge. If the Travis-CI build fails notifications are sent to all participants of the pull request. If any other validation steps fail, an indication of the failure is affixed to the PR in github. The Pull Request should never be approved unless the entire validation passes. Sometimes (like in the example above), the solution is simply to ensure the PR branch has merged master into itself. If any PRs are approved and merged into master while the current PR is under review, the validation process will mark the PR as failed until it has been fast-forwarded.

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.