-
Notifications
You must be signed in to change notification settings - Fork 1
How to Contribute: Git Practices
For statnet collaborators, use the private statnet/lolog-private repository, not the public statnet/lolog repository
git clone https://github.com/statnet/lolog-private.git lolog
We will keep master in statnet/lolog-private synched with master in statnet/lolog, so don't make pull requests to master that you are not ready to have made public.
All active development should happen on your own branch, not on master. Create a new branch on your local machine with:
git branch branch_name
git checkout branch_name
Synch it with github using
git push origin branch_name
you should now see your branch on github.
Play around, explore, research ideas and break things on your branch. Commit and push these changes to your branch with
git commit . -m "I did stuff"
git push origin branch_name
when you are finished with your branch (either because it has been merged into master, or you don't need it anymore), go to the project page on github, click branches and delete your branch by clicking the trash button.
Documentation is written automatically by roxygen2. do not edit .Rd files manually. Make sure these are up to date with
roxygen2::roxygenize('.', roclets='rd')
Often in research we will touch a lot of code in a lot of different places to hack through and test a research hypothesis. Take a step back from your implementation and review whether the solution path is the best design (from a CS perspective) to implement.
Sometimes the best solution after you've figured out that an idea will work is to create a whole new branch, copying over chunks the implementation from your research branch into a new clean design. If you are implementing a new method, think carefully about whether it should be incorporated directly into lolog or whether it should exist in its own package extending lolog.
Make sure that you don't have any local files that should be commited, but are sitting untracked. you can see what is untracked with
git status
You should see no Changes not staged for commit. Review the untracked files and make sure there are no .Rd, .R, .cpp or .h files. You can start tracking files with
git add path/to/file
Before integrating any changes with the master branch, you will want to review your code to ensure that it is ready for merge. The first step is to make sure it is compatible with the current master, which may have changed since you created the branch. The following code will update your local master branch and merge it into your development branch.
git checkout master
git pull
git checkout branch_name
git merge master
you may need to resolve conflicts at this point. It is generally a good idea to synch up with master on a regular basis so that your branch doesn't get too divergent.
For each function, write a test in the tests/testthat directory. This helps ensure that
- Your code is doing what you think
- Future changes didn't break your functionality
If the code is in C++ create a files test_SomethingOrOther.h and test_SomethingOrOther.cpp with your new tests and edit registerLologTests() to include your new tests.
We can be a bit flexible on the "every function must be tested" requirement, but at the very least, every pull request with new functionality should have new tests.
Run:
R CMD check --as-cran lolog_*.tar.gz
The package must pass with no NOTEs, WARNINGs or ERRORs to be merged with master. The exception to this is a NOTE about the license extending MIT.
lolog uses travis ci for continuous integration. A green check mark next to a commit means that it passed R CMD check -as-cran with no WARNINGS. To see if there are any notes, click the check mark and view the log.
Now you are ready to merge into master, but don't do it. Instead, go to your branch in github, and click pull request. A project administrator will then review the changes and merge them if there are no issues.
Don't worry, you can't break anything by making a pull request. No changes to master will be made until the change has been reviewed.
External collaborators should fork the statnet/lolog repository though the github UI. And do development on their forked repository. When your changes are ready, file a pull request to statnet/lolog.
Before you file a pull request, make sure your repo is up to date with the statnet/lolog repo and follow all the steps in the Incorporating changes into master section.
git remote add upstream https://github.com/statnet/lolog.git
git fetch upstream
git pull upstream master
After a pull request is merged, the change should be propagated to the public repo. You'll want to have the public repo as a remote:
git clone https://github.com/statnet/lolog-private.git lolog
cd lolog
git remote add public https://github.com/statnet/lolog.git
Then whenever changes are to be pushed to the public repo, run:
git push public master