NEST Git workflow

Basic Git setup

The NEST development takes place in a repository using the Git version control system. The following sections document the general steps required to set up a working installation of Git. If you have Git set up already, skip to the Suggested development workflow section.

Installation and global setup

  1. Install Git.

  2. Introduce yourself to Git:

git config --global user.email you@yourdomain.example.com
git config --global user.name "Your Name Comes Here"

Setting up your GitHub account

The NEST source code is hosted in a public repository on GitHub. If you don’t have a GitHub account already, please create one.

You then need to configure your account to allow write access - please see the article on generating SSH keys on the GitHub help website.

Making your own copy (fork) of NEST

This needs to be done only once. The instructions here are very similar to the instructions on GitHub, which you can refer to for more details. This documentation includes a version specific to NEST.

Creating your own forked copy of NEST

  1. Login to your GitHub account.

  2. Go to the NEST source code repository on GitHub.

  3. Click on the Fork button.

After a short pause, you should find yourself at the home page for your own forked copy of NEST.

Downloading your fork

After forking the repository, you need to download (clone) it to your local computer to work with the code.

The following commands should do it. The next section explains the commands.

git clone git@github.com:your-user-name/nest-simulator.git
cd nest-simulator
git remote add upstream git://github.com/nest/nest-simulator.git

Commands explained

Clone your fork

git clone git@github.com:your-user-name/nest-simulator.git

This downloads your fork to your local system. Investigate. Change directory to your new repository: cd nest-simulator. Then git branch -a to show you all branches. You’ll get something like:

* master
remotes/origin/master

This tells you that you are currently on the master branch, and that you also have a remote connection to origin/master. The master branch is the default branch and this is where code that has been reviewed and tested resides. origin/master is just a copy of the master branch on your system on the remote.

What remote repository is remote/origin? Try git remote -v to see the web address for the remote. It should point to your GitHub fork.

Next, you connect your local copy to the central NEST GitHub repository, so that you can keep your local copy and remote fork up to date in the future. By convention, the main source code repository is usually called upstream.

Link your repository to the upstream repository

cd nest-simulator
git remote add upstream git://github.com/nest/nest-simulator.git

Note

We’ve used git:// in the web address instead of git@. The git:// web address is read only and ensures that you don’t make any accidental changes to the upstream repository (if you have permissions to write to it, of course).

Check that you have a new remote set up with git remote -v show. You should see something like this:

upstream     git://github.com/nest/nest-simulator.git (fetch)
upstream     git://github.com/nest/nest-simulator.git (push)
origin       git@github.com:your-user-name/nest-simulator.git (fetch)
origin       git@github.com:your-user-name/nest-simulator.git (push)

Suggested development workflow

Once you’ve already set up your forked copy of the NEST source code repository, you can now start making changes to it. The following sections document the suggested Git workflow.

Basic workflow

In short:

  1. Start a new branch for each set of changes that you intend to make. See the Making a new feature branch section below.

  2. Hack away! See the section that documents the Editing workflow - command list.

  3. When you are satisfied with your edits, push these changes to your own GitHub fork, and open a pull request to notify the development team that you’d like to make these changes available at the upstream repository. The steps for this are documented in the Creating a pull request section.

This suggested workflow helps to keep the source code repository properly organized. It also ensures that the history of changes that have been made to the source code (called commit history) remains tidy, making it easier to follow.

Making a new feature branch

Before you make any changes, ensure that your local copy is up to date with the upstream repository.

  1. Go to (checkout) the default master branch

git checkout master
  1. Download (fetch) changes from upstream

git fetch upstream
  1. Update your master branch - merge any changes that have been made upstream

git merge upstream/master --ff-only
  1. Update the remote for your fork

git push origin master

We suggest using the --ff-only flag since it ensures that a new commit is not created when you merge the changes from upstream into your master branch. Using this minimises the occurrence of superfluous merge commits in the commit history.

Now that you have the latest version of the source code, create a new branch for your work and check it out:

git checkout -b my-new-feature master

This starts a new branch called my-new-feature from master.

It is extremely important to work on the latest available source code. If you work on old code, it is possible that in the meantime, someone else has already made more changes to the same files that you have also edited. This will result in merge conflicts and resolving these is extra work for both the development team and you. It also muddles up the commit history of the source code.

Editing workflow - command list

  1. Improve modified_file with your text editor/IDE.

  2. Confirm what files have changed in the repository.

git status
  1. Review the changes you’ve made (optional).

git diff
  1. Inform Git that you want to save these changes.

git add modified_file
  1. Save these changes.

git commit
  1. Push these changes to the remote for your fork.

git push origin my-new-feature

Editing workflow - commands explained

  1. Make some changes. When you feel that you’ve made a complete, working set of related changes, move on to the next steps.

  2. Please ensure that you have followed the coding guidelines for C++ and SLI coding guidelines.

  3. Test your changes by building the source code and running the tests. (Usually cmake, make, make install, make installcheck. Please see the installation section for details.)

  4. Check which files have changed with git status. You’ll see a listing like this one:

    On branch my-new-feature
    Changed but not updated:
    (use "git add <file>..." to update what will be committed)
    (use "git checkout -- <file>..." to discard changes in working directory)
    
    modified:   README
    
    no changes added to commit (use "git add" and/or "git commit -a")
    
  5. Compare the changes with the previous version using git diff. This brings up a simple text browser interface that highlights the difference between your files and the previous version like this:

     diff --git a/development_workflow.rst b/development_workflow.rst
     index f05f0cd..e581f00 100644
     --- a/development_workflow.rst
    +++ b/development_workflow.rst
     @@ -8,17 +8,22 @@ layout: index
    
  6. Inform Git of what modified or new files you want to save (stage) using git add modified_file. This puts the files into a staging area, which is a list of files that will be added to your next commit. Only add files that have related, complete changes. Leave files with unfinished changes for later commits.

  7. To commit the staged files into the local copy of your repository, run git commit. Write a clear Git commit message that describes the changes that you have made. Please read this article on writing commit messages. If a commit fixes an open issue on the GitHub issue tracker, include Fixes #issue_number in the commit message. GitHub finds such keywords and closes the issue automatically when the pull request is merged. For a list of all keywords you can use, refer to this GitHub help page. After saving your message and closing the editor, your commit will be saved.

  8. Push the changes to your forked repository on GitHub:

    git push origin my-new-feature
    

Assuming you have followed the instructions in these pages, Git will create a default link to your GitHub repository called origin. In Git >= 1.7 you can ensure that the link to origin is permanently set by using the --set-upstream option:

git push --set-upstream origin my-new-feature

From now on, Git will know that my-new-feature is related to the my-new-feature branch in your own GitHub repository. Subsequent push calls are then simplified to the following:

git push

It often happens that while you were working on your edits, new commits have been added to upstream that affect your work. In this case, you will need to reposition your commits on the new master. Please follow the git rebase instructions.

Next, we see how to create a pull request.

Creating a pull request

When you feel your work is finished, you can create a pull request (PR). GitHub has a nice help page that outlines the process for submitting pull requests.

Please check out our coding style guidelines and code review guidelines prior to submitting it.