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.
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: (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.
- Fork the project on GitHub (http://www.github.com/numenta/nupic).
- Clone the fork to your local environment for development.
Do Good Stuff
- Create a feature branch off
masterto house atomic code changes.
- Satisfy the contribution requirements (see NuPIC Contribution Standards).
- Push changes to your fork (or remote branch).
- Submit a pull request from your fork or branch to the
masterbranch for review.
- Allow PR Validation to complete
- Incorporate community feedback.
- Push changes to your fork/branch – the pull request will automatically update and PR validation will run again.
- 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).
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
After validation has passed, the PR will be ready to merge:
A Pull Request, Step by Step
Below is a detailed view of all the steps happening behind the scenes for a pull request.
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 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.
- 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.