Skip to content

Latest commit

 

History

History
51 lines (31 loc) · 4.3 KB

CONTRIBUTING.md

File metadata and controls

51 lines (31 loc) · 4.3 KB
Raw

Contributing Guidelines

Pull requests

Requirements for making a pull request:

  • Some knowledge of git
  • Some knowledge of GitHub

Read more about pull requests on GitHub at https://help.github.com/articles/using-pull-requests/. If you haven't done this before, Hadley Wickham provides a nice overview of git (http://r-pkgs.had.co.nz/git.html), as well as best practices for submitting pull requests (http://r-pkgs.had.co.nz/git.html#pr-make).

Then:

  • Fork the repo to your GitHub account
  • Clone the version on your account down to your machine from your account, e.g,. git clone [email protected]:benmarwick/<package name>.git
  • Make sure to track progress upstream (i.e., on our version of the package at benmarwick/<package name>) by doing git remote add upstream [email protected]:benmarwick/<package name>.git. Each time you go to make changes on your machine, be sure to pull changes in from upstream (aka the ropensci version) by doing either git fetch upstream then merge later or git pull upstream to fetch and merge in one step
  • Make your changes (we prefer if you make changes on a new branch)
  • Ideally included in your contributions:
  • Well documented code in roxygen docs
  • If you add new functions or change functionality, add one or more tests.
  • Make sure the package passes R CMD CHECK on your machine without errors/warnings
  • Push up to your account
  • Submit a pull request and participate in the discussion.

Documentation contributions

Documentation contributions are surely much needed in every project as each could surely use better instructions. If you are editing any files in the repo, follow the above instructions for pull requests to add contributions. However, if you are editing the wiki, then you can just edit the wiki and no need to do git, pull requests, etc.

All of the function documentation is generated automatically. Please do not edit any of the documentation files in man/ or the NAMESPACE. Instead, construct the appropriate roxygen2 documentation in the function files in R/ themselves. The documentation is then generated by running the document() function from the devtools package. Please consult the Advanced R programming guide if this workflow is unfamiliar to you. Note that functions should include examples in the documentation. Please use \dontrun for examples that take more than a few seconds to execute or require an internet connection.

Likewise, the README.md file in the base directory should not be edited directly. This file is created automatically from code that runs the examples shown, helping to ensure that they are functioning as advertised and consistent with the package README vignette. Instead, edit the README.Rmd source file in manuscripts and run make to build the README.

Repository structure

This repository is structured as a standard R package following the conventions outlined in the Writing R extensions manual. A few additional files are provided that are not part of the built R package and are listed in .Rbuildignore, such as .travis.yml, which is used for continuous testing and integration.

Code

All code for this package is found in R/, (except compiled source code, if used, which is in /src). All functions should be thoroughly documented with roxygen2 notation; see Documentation.

Bug reports must have a reproducible example and include the output of devtools::session_info() (instead of sessionInfo()). We recommend using Hadley Wickham's style guide when writing code (http://adv-r.had.co.nz/Style.html).

Testing

Any new feature or bug-fix should include a unit-test demonstrating the change. Unit tests follow the testthat framework with files in tests/testthat. Please make sure that the testing suite passes before issuing a pull request. This can be done by running check() from the devtools package, which will also check for consistent documentation, etc.

This package uses the travis continuous testing mechanism for R to ensure that the test suite is run on each push to Github. An icon at the top of the README.md indicates whether or not the tests are currently passing.

Questions or comments?

Do not hesitate to open an issue in the issues tracker to raise any questions or comments about the package or these guidelines.