This document outlines how to contribute to the development of pastclim
. The
package is maintained on a voluntary basis, so help is always appreciated.
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.
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.
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.
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.
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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.