To clone this project locally, issue
git clone https://github.com/djsaunde/spiketorch.git # clones GitHub repository into directory "spiketorch"
in the directory of your choice. This will place the repository's code in a directory titled spiketorch.
All development should take place on a branch separate from master. To create a branch, issue
git branch [branch-name] # create new branch
replacing [branch-name] with a simple and memorable name of choice; e.g., git branch dan. Switch to the newly created branch using
git checkout [branch-name] # switch to a different branch of the repository
Note: Issue git branch with no arguments to list all branches currently being tracked, with an asterisk next to the currently used branch; e.g.,
$ git branch # list all branches and indicate current branch
* dan
devel
hananel
master
If new branches have been created on the remote repository, you may start tracking them with git pull --all, and check them out using git checkout [branch-name], as before. git branch -a will list all locally tracked branches, and well as list all remote branches (which can be checked out!).
After making changes to the repository, issue a git status command to see which files have been modified. Then, use
git add [file-name(s) | -A] # add modified or newly created files
to add one or more modified files (file-name(s)), or all modified files (-A or --all). These include newly created files. Issue
git commit -m "[commit-message]" # Useful messages help when reverting / searching through history
to "commit" your changes to your local repository, where [commit-message] is a short yet descriptive note about what changes have been made.
Before pushing your changes to the remote repository, you must make sure that you have an up-to-date version of the master code. That is, if master has been updated while you have been making your changes, your code will be out of date with respect to the master branch. Issue
git pull # gets all changes from remote repository
git merge master # merges changes made in master branch with those made in your branch
and fix any merge conflicts that may have resulted, and re-commit after the fix with
git commit # no -m message needed; merge messages are auto-generated
Push your changes back to the repository onto the same branch you are developing on. Issue
git push [origin] [branch-name] # verbose; depends on push.default behavior settings
or,
git push # concise; again, depends on push.default behavior
where [origin] is the name of the remote repository, and [branch-name] is the name of the branch you have developed on.
Note: See (push.default)[https://git-scm.com/docs/git-config#git-config-pushdefault] for more information.
To merge your changes into the master branch (the definitive version of the project's code), open a pull request on the webpage of the project. You can select the base branch (typically master, to merge changes into the definitive version of the code) and the compare branch (say, dan, if I added a new feature locally and want to add it to the project code). You may add an optional extended description of your pull request changes. If there are merge conflicts at this stage, you may fix these using GitHub's pull request review interface.
Assign reviewer(s) from the group of project contributors to perform a code review of your pull request. If the reviewer(s) are happy with your changes, you may then merge it in to the master branch. Code review is crucial for the development of this project, as the whole team should be held accountable for all changes.
Here's a schematic of the process for submitting a pull request to the master branch of the GitHub repository:
