This document outlines how to contribute to the development of pastclim. The package is maintained on a voluntary basis, so help is always appreciated.
The basic process of contributing
Development work for pastclim occurs in the dev branch. So, if you want to propose any changes, you should work on dev. Start by forking the project onto your github repository, make the changes directly in your fork (either in the dev branch, or make a custom branch). After updating all the documentation and checking that all tests pass (see below), start a Pull Request. Your proposed changes will be reviewed, and you might be asked to fix/improve your code. This can be an iterative process, requiring a few rounds of revision depending on the complexity of the code.
Functions should be documented using roxygen. If any of your changes affects the documentation , you should rebuild it. From the root directory of the package, simply run:
devtools::document()If you implemented a new functionality, or patched a bug, you should consider whether you should add an appropriate unit test. pastclim uses the testthat framework for unit tests. You should make sure that tests work with :
devtools::test()Finally, before you submit a push request, you should check that your changes don’t break the build. You can do that with check, which also builds the vignette and runs the tests.:
devtools::check()Make sure that you have resolved all warnings and notes raised by devtools::check()!
Once you have followed those 3 steps, you are ready to make your Pull Request. Your changes will go through automatic continuous integration, which will check the impact of those changes on multiple platforms. If everything goes well, you will see a green tick on your submission.
Fixing typos
If you spot typos, spelling mistakes, or grammatical errors in the documentation, you should fix them directly in the file that describes the function. This is the .R file in the R directory, NOT the .Rd file in the man directory. .Rd files are automatically generated by roxygen2 and should not be edited by hand. We recommend that you study first how roxygen2 comments work.
Functional changes
If you want to make a change that impacts the functioning of pastclim, it’s a good idea to first file an issue explaining what you have in mind. If the change is meant to fix a bug, then
add a minimal reprex.
A good reprex is also the perfect starting point for writing a unit test, which should accompany any functional change in the code. Unit tests are also essential when fixing bugs, so that you can both demonstrate that the fix work, and prevent future changes from undoing your work. For unit testing, we use testthat; you will find tests under tests, with a file dedicated to each function, following the convention test_my_function.R for naming files. When creating tests, try to make use built-in datasets, rather than adding data files to the package.
Ideally, the body of your Pull Request will include the phrase Fixes #issue-number, where issue_number is the number on Github. In this way, your Pull Request will be automatically linked to the issue, and the issue will be closed when the Pull Request is merged in.
For user-facing changes, add a bullet to the top of NEWS.md (i.e. just below the first header). Follow the style described in https://style.tidyverse.org/news.html.
Our continuous integration checks that the Pull Request does not reduce test coverage.
Code style
New code should follow the tidyverse style guide. You can use the styler package to apply these styles, but please don’t restyle code that has nothing to do with your PR.
Lots of commenting in the code helps mantainability; so, if in doubt, always add an explanation to your new code.
Code of Conduct
Please note that the tidyverse project is released with a Contributor Code of Conduct. By contributing to this project you agree to abide by its terms.