*DEPRECATED* nupic.core feature branch workflow

The following is deprecated, should not apply to current practices, and left here for posterity. These instructions may change or go away entirely at any time. Follow at your own risk -- you have been warned. -AM 2017-04-19

---

numenta/nupic.research includes code that requires nupic.research.bindings, a python package provided by the numenta/nupic.research.core repository, itself a fork and superset of numenta/nupic.core. The following includes instructions for configuring your local working environment to support a development workflow that allows you to easily switch back-and-forth between mainline and experimental bodies of code.

The following instructions assume a single nupic.core checkout on your local machine, if you have not already done so, go ahead and clone numenta/nupic.core at a location of your choosing. All subsequent git commands are assumed to be executed in the root of that nupic.core directory.

Setup your remotes

We'll add the main numenta/nupic.research.core repository as experimental-upstream:

git remote add experimental-upstream https://github.com/numenta/nupic.research.core

Fork numenta/nupic.research.core in GitHub (you should know how to do this already)

Now add your fork as the experimental-origin remote repository (you will need to fixup the url in the example below replacing "[YOUR USERNAME HERE]" with your github username):

git remote add experimental-origin https://github.com/[YOUR USERNAME HERE]/nupic.research.core

Work in a feature branch

The following assumes that the local nupic.core git repository has been configured for an upstream remote pointing to numenta/nupic.core, and an origin remote pointing to your fork of numenta/nupic.core. If that is not how your repository is configured, you will need to adjust the instructions.

Create a feature branch specific to a task or project based on a recent version of upstream/master:

git fetch upstream
git checkout -b MY_FEATURE_BRANCH upstream/master

Do work... when ready, add your changes and commit as usual.

Use in experimental context

Now, to apply changes in experimental context you will need to create another temporary branch that is based on a recent version of experimental-upstream/master so you can merge your experimental not-yet-canonicalized nupic.core feature branch:

git fetch experimental-upstream
git checkout -b MY_FEATURE_BRANCH-experimental experimental-upstream/master
git merge MY_FEATURE_BRANCH

This should go smoothly, but you may need to resolve merge conflicts before continuing.

Create your nupic.core pull requests as you would normally and follow established development process. Once merged into master, numenta/nupic.research.core will be updated separately to include the latest nupic.core eliminating the need to retain the temporary branch locally.