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¶
Introduce yourself to Git:
git config --global user.email firstname.lastname@example.org 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¶
Login to your GitHub account.
Go to the NEST source code repository on GitHub.
Click on the
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 email@example.com:your-user-name/nest-simulator.git cd nest-simulator git remote add upstream git://github.com/nest/nest-simulator.git
Clone your fork
git clone firstname.lastname@example.org:your-user-name/nest-simulator.git
This downloads your fork to your local system. Investigate. Change directory
to your new repository:
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
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
What remote repository is
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
Link your repository to the upstream repository
cd nest-simulator git remote add upstream git://github.com/nest/nest-simulator.git
git:// in the web address instead of
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 email@example.com:your-user-name/nest-simulator.git (fetch) origin firstname.lastname@example.org: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.
Start a new branch for each set of changes that you intend to make. See the Making a new feature branch section below.
Hack away! See the section that documents the Editing workflow - command list.
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
upstreamrepository. 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
Go to (checkout) the default master branch
git checkout master
Download (fetch) changes from upstream
git fetch upstream
Update your master branch - merge any changes that have been made upstream
git merge upstream/master --ff-only
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
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¶
modified_filewith your text editor/IDE.
Confirm what files have changed in the repository.
Review the changes you’ve made (optional).
Inform Git that you want to save these changes.
git add modified_file
Save these changes.
Push these changes to the remote for your fork.
git push origin my-new-feature
Editing workflow - commands explained¶
Make some changes. When you feel that you’ve made a complete, working set of related changes, move on to the next steps.
Please ensure that you have followed the coding guidelines for C++ and SLI coding guidelines.
Test your changes by building the source code and running the tests. (Usually
make installcheck. Please see the installation section for details.)
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")
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
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.
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_numberin 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.
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
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:
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.