This page details the proper process for submitting code into the NuPIC codebase. If you are interested in making code contributions, you’re in the right place!
General Guidelines
- Ensure your contribution fits into the Project Roadmap.
- Modularize your contributions into small packages.
- Include detailed commit messages.
- Pull requests should only address one issue in the issue tracker.
- Discuss Log Patch Review
1. Review the Roadmap
As defined in our Contributor Model, the Project Roadmap defines the strategic direction of development for NuPIC and associated projects. Please review this document to ensure that your contribution fits within this stratetic direction. If it does not, your proposal may be rejected.
The Roadmap is maintained by project Reviewers. If you think it needs to be updated in a way that includes room for your contribution, use the NuPIC Developer Forum to plead your case.
2. Define the proposed change
We don’t like to see pull requests pop up with no explanation. So if one does, we’ll generally close it and ask the author to describe the proposed new feature or bugfix to the community.
2.1 Discuss your proposal
If you have a feature you’d like to add to NuPIC, that’s great! To increase the chances it will be merged into master, it’s a good idea to build some community support and discuss this change with the community. Create a topic in the NuPIC Developer Forum describing the feature you’re thinking about adding. If you have code to reference, keep this on your own fork until you feel there is enough support and feedback to submit a pull request. Other community members might like your idea and have suggestions on how to go about it. You’ll probably get some good ideas about how to present the API for your feature.
If the community doesn’t understand your proposal, or disagrees with the direction you’re going, there is less of a chance it will get merged into master.
2.2 Log an issue, issue-htm.java
You can use the links below to create new issues.
This is where you’ll describe the problem you’re facing, or observing. If this is the continuation of a discussion on the NuPIC Developer Forum, find the original topic and provide a link back to the original discussion that caused the issue to be logged. You might get some technical discussion from other community members here. It would also be a good idea to reply the original NuPIC Developer Forum post with a link to the issue you’ve created, effectively taking the implementation discussion into the issue tracker.
2.3 Issue Re-assignment
Any issue assignments may undergo re-assignment if:
- There has been no substantive activity on the issue in a 2 week period, and
- There has been no communication received about changes in the assigned developer’s circumstances.
In most cases, collaboration is encouraged and so in the above cases, you may be asked to collaborate on an issue with another developer, or in an extreme case, the issue could be re-assigned to another developer.
The main concern is to ensure that developer’s don’t waste their time and that everyone gets a fair chance to contribute to the project - while also fostering an atmosphere where developers can learn and grow.
3. Do the work
3.1 Fork the repository
We don’t do any work on topic branches in NuPIC. There is only one branch, and that’s master. Once you’ve forked NuPIC, you can create as many topic branches on your local checkout as you like. That’s probably where you’ll do most of your work. This process is described in detail on the Developer Workflow wiki page.
3.2 Create a pull request
Contributors should never push their changes directly into the project.
To submit a patch, create a pull request back to the project that references the originating issue using keywords in commit messages or pull request descriptions.
To discuss a patch, people may comment on the pull request, on the commit, or elsewhere. (Major discussions about the validity of the initial idea should have been vetted on the NuPIC Developer Forum, however.)
Once you think your pull request is ready to be merged, add a comment referencing a reviewer letting us know it’s ready to merge, and a Committer will tag it as “ready”. This will indicate to Reviewers that your PR is prepared for master. If you fail to tell us your PR is ready for review, we might forget to look at it in a timely fashion.
Soon, a Reviewer will probably come along to look at your work. It’s their job to ask for improvements to incorrect patches, and will reject your patch if you don’t respond constructively. Reviewers are there to keep the standards of the project in place, so don’t take offense to someone asking you to adhere to our coding standards or add more test coverage.
If another Contributor disagrees with your implementation of the patch, they might express that by submitting a pull request to your patch with changes. Now it’s your job to review their changes. If you like their changes, you can merge that PR into yours. This is how we improve each others’ code and collaborate for a better project.
3.2 Pull Request Protocols
-
Every Pull Request must be associated to one Issue using a keyword, for example
Fixes #123indicates that this PR fixes issue number 123. PRs that do not fix an issue will not be merged. -
Pull Requests should be ready for review when created. Do not create “work in progress” pull requests. You can easily compare your progress on a remote branch to
masterwith the GitHub UI. It is completely fine to add a link to your WIP branch on the issue itself. -
During the review cycle, the tags
status:in progress,status:ready, andstatus:help wantedwill indicate whether the PR requires further review, needs work from the PR author(s), or is stalled and needs assistance.
- PRs labeled “status:in progress” will not be reviewed until author
takes further action - PRs labeled “status:ready” will be prioritized for review
- PRs labeled “status: help wanted” indicates PR author is stuck and needs assistance
- Open PRs labeled
status:in progressorstatus:help wantedwith no activity for over a
month will be closed automatically.
- PR will receive a comment “ping” at least 5 days before the PR is closed.
- Author is free to open another PR.
4. Prosper!
Not just you, for contributing to an awesome open source machine intelligence platform, but the entire NuPIC community for working towards a common goal. 