-
Notifications
You must be signed in to change notification settings - Fork 186
Git guidelines
This note is to help contributors use barely enough git to get through the process of contributing to the project on github. If you haven't set up git yet, start here: https://help.github.com/articles/set-up-git
The instructions here refer to command line operation of git. If you're using a GUI client or RStudio's git interface it might be easier and require fewer operations. See the specific client's documentation for details, but they should have buttons that approximate the commands mentioned below. Here are some GUI clients:
http://www.rstudio.com/ide/docs/version_control/overview
To create a copy of quanteda as a local git repository, use the command clone
git clone https://github.com/kbenoit/quanteda.git
(see http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository#Cloning-an-Existing-Repository )
There are two permanent branches for the project, one called 'master' and one called 'dev'. The 'master' branch is a live current release, in the sense that anyone who lands on our github page and follows the instructions will end up with this copy of quanteda. For that reason, we don't want to make changes to the master branch until we have at least run through a few basic example like the one on the readme.
So, for new features and ongoing development, please work on the 'dev' branch.
To see what branches there are, and which one you're on, use:
git branch
To see what branch you're on, and what changes you have made, use
git status
To switch to a branch, use
git checkout _nameofbranch_
Switch to the dev branch.
git checkout dev
Once you've switched to the dev branch, pull the latest changes from github (the clone command should have automatically set up github as your remote repository):
git pull
Make the changes you would like to make. See the suggested development workflow for one way to develop and document new code.
Add the changes to your next commit, and then commit them:
git add -A
(The -A option here indicates that git will add all changed files in your local quanteda directory and remove any deleted ones)
git commit -m 'this is my commit message'
Leave an explanatory message with each commit.
When you are ready to upload to github (assuming the branch you are working on is named dev):
git push origin dev
You should just be prompted for your github username and password, but depending on how you initially set up git you might have to do some messing around with ssh keys or setting up your origin branch. If you have cloned from github, your origin should already be configured correctly. If the push is successful, you'll see a 'Delta' message. For further help see: https://help.github.com/articles/generating-ssh-keys , but this shouldn't be necessary.
If two people have simultaneously edited the same part of the same file, the push will fail, and you'll be asked to resolve the conflict somehow --- it depends on your setup but usually this involves manually editing the file in a text editor. This is messy, which is why it's usually better to contribute by adding a new .R file than editing one we are already working on. For further help see: http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts
When the dev branch has been well-tested and doesn't contain too much experimental code, it can be merged into the master branch to update the 'official' version. To do this:
Switch to master branch:
git checkout master
Merge in the dev branch:
git merge dev
If there is a conflict (the same lines in the same file have been edited in different ways on the two branches), use git mergetool to try to manually merge the files.
Useful resources: