Contributors' Guide

This page collects guidelines for contributing to refund.
Before starting to work on the code, please search through the issue tracker to see if other people have discussed or worked on related issues.

General procedure

for anybody not in the refunders group:

• please create a fork of the repository and check out a new branch off of /devel to work on
• modify the recipients lines in https://github.com/refunders/refund/blob/devel/.travis.yml so you get the report from TravisCI about the success of R CMD check, not Julia or Fabian.
• once you're satisfied with your changes and R CMD check passes, please create a pull request without the changed .travis.yml file
• please remember to use Github's issue tracker -- if your changes are related to an issue there, please reference the issue in your commit messages / in the description of your pull request, see here.

for refunders group members developing new features:

• open a new branch from branch /devel
• modify the recipients lines in https://github.com/refunders/refund/blob/devel/.travis.yml so you get the report from TravisCI about the success of R CMD check, not Julia or Fabian.
• once you're satisfied with your changes and R CMD check passes, merge your changes back into /devel and then revert the induced changes in the .travis.yml file (sorry, automating this surpasses my Git skills)
• please remember to use Github's issue tracker -- if your changes are related to an issue there, please reference the issue in your commit messages, see here. You can also reference/describe commits in the discussion, see here.

for refunders group members fixing bugs:

• same as above, except that bug fixes should be merged into both /master and /devel. Especially for changes to /master, it's critical to make sure that R CMD check passes with your changes before pushing your changes to the remote. If that doesn't work out for you, create a pull request from your modified branch and let the other team members help you.

Coding standards

We don't really have a lot of those at the moment, so please use your common sense and good taste. In order to contribute successfully, you must have a basic understanding of Git and Github (local and remote repositories, forks, branches, pull requests, issue tracking, etc..) and R package structure.
Every commit that is pushed to the remote repository triggers R CMD check performed on the preceding, current and development versions of R on Travis CI. If any of those should fail, please read the error messages and warnings carefully and fix all of them before merging anything into /devel or /master or issuing a pull request.

Rules:

1. We use roxygen2 for documentation. Do not write .Rd files or NAMESPACE directives manually.
2. We use testthat for testing on the /devel branch. If you add new functionality, you should write tests for that functionality as well.

Recommendations:

1. Take a really good look at existing functionality in refund before adding new features or functions and aim for argument names, return objects and function behavior that are as similar as possible to the stuff we already have. refund is a collaborative endeavour with a large fluctuation of active contributors of diverse research interests and varying programming proficiency, so we will never have a perfect and consistent user interface. But we can at least try to become better at this... 😉
2. Try to avoid adding new external dependencies -- refund imports a lot of other packages as it is, we do not want this list to become even longer. More dependencies means more difficult maintenance, a greater risk of name clashes, longer R CMD check times on Travis CI and also make it more cumbersome for people to install and use the software.