Thanks for checking out our project! If you haven’t already, please check out the readme for general info about this project.
All contributors will be expected to follow our code of conduct.
If you’re not a member of the Weecology lab, we ask that you use one of the following two methods for contributing:
Create an issue – if you spot any typos, bugs, or have general suggestions, etc. You can also use this to participate in ongoing discussions. For more info, please check out this Github guide.
Fork and create a pull request – if you have suggested bugfixes or changes. For more info, please check out this Github guide. We ask that you follow our guidelines below on documentation and testing.
If you’re actively working on this repo, then you should have write access to create branches for any new features or bugfixes. Please see the lab-wiki for info on using branches in a shared repository.
If you don’t have write access and you would like to, please contact @gmyenni for access.
If you are contributing code to this project, you generally don’t need any additional packages, since the documentation will be written as comments in the R scripts. If you are also building the package, see the section below for more details.
In most cases, you’ll be creating a new function and then documenting it. You can check the existing functions for examples, but here’s a basic template:
#' @title {this is the heading for the help file}
#'
#' @description {A description of the function}
#'
#' @param {name of a function argument} {what the argument does}
#'
#' @return {what is returned from the function}
#'
#' @examples
#' {R code that is an example use of the function}
#'
#' @export
#'
newfunc <- function() ...Note that you can also include links to other functions, math formatting, and more. For more details, see the chapter on documentation in Hadley Wickham’s book for R packages.
If you are adding new functionality, please include automated tests to verify that some of the basic functionality is correct.
Automated testing uses R scripts, that live in the tests/testthat/ subfolder for the package. If you are adding a new file, please name it as test-{concept}.R.
As a general rule, you don’t need to test all possible inputs and outputs for a function, but you should test some important aspects:
You can see the existing tests as examples of how to organize your tests, but note that there are several different kinds of expect_ functions that test for different things. For more details, see the chapter on testing in Hadley Wickham’s book for R packages.
To fully build the package, including documentation, running-tests, you will need the roxygen2, the testthat, and the devtools package.
Specific operations are then done by calling the appropriate functions from within R, while your working directory is somewhere in the package folder.
The suggested workflow is:
devtools::document() to generate the documentation files and update the NAMESPACE file.devtools::install() to install the new version of the package.devtools::test() to run the test scripts on the new version of the package.If you are also prepping the package as a whole, then you will also want to run devtools::check() and/or devtools::check_cran() to make sure that the package is complete. Note that you need an up-to-date TeX/LaTeX distribution for running devtools::check() and/or devtools::check_cran() due to the rendering of the package manual.
For more info, see the GitHub repo for the devtools package.
This document is based on the CONTRIBUTING file associated with the Beta release of the portalr package and is used under the MIT License.