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 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¶
Login to your GitHub account.
Go to the NEST source code repository on GitHub.
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:
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
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.
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 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¶
Improve
modified_file
with your text editor/IDE.Confirm what files have changed in the repository.
git status
Review the changes you’ve made (optional).
git diff
Inform Git that you want to save these changes.
git add modified_file
Save these changes.
git commit
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
cmake
,make
,make install
,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 astaging 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, includeFixes #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.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.