R CMD checklocally for you. It’s a good idea to do that before you touch anything, so you have a baseline.
.Rdfiles by hand. More below.
_pkgdown.yml, i.e. to make sure that a function appears there.
#15syntax and the issue slug for context. If the PR is meant to close an issue, make sure one of the commit messages includes text like
fixes #101. Provide the issue number and slug in the description, even if the issue is mentioned in the title, because auto-linking does not work in the PR title.
NEWS.mdwith a concise description of the change, if it’s something a user would want to know when updating the package. dplyr’s
NEWS.mdis a good source of examples. Note the sentence format, the inclusion of GitHub username, and links to relevant issue(s)/PR(s). We will handle any organization into sub-sections just prior to a release. What merits a bullet?
dribble, whenever it makes sense.
There is a high-level interface for the typical user. These functions help you accomplish the most common tasks, hopefully in a natural way. Examples:
drive_download(). A few hand-picked functions support passing extra parameters through to the API request via
..., but we don’t do this across the board.
There is also a low-level interface that is used internally. An example is the function
request_generate(). These functions are exported for use by programming-oriented users who are willing to read Drive API docs and want to do things we haven’t made available in the high-level interface.
Use templates or inheritance to repeat documentation whenever it is helpful, but without actually repeating its source.
Use internal and external links liberally, i.e. to other docs in googledrive or to Drive API resources.
We encourage working examples that include any necessary setup and teardown. In most cases, you’ll have to put them inside a
It’s nice if a pull request includes the result of running
devtools::document(), to update
NAMESPACE and the
.Rd files, but that’s optional. A good reason to NOT
document() is if you have a different version of roxygen2 installed and that sprays minor formatting changes across
.Rd files that have nothing to do with the PR.
We use testthat.
We have many tests that (1) require authorization and that (2) rely on the existence of specific files and folders. Therefore, to fully test googledrive, you have to do some setup.
For small changes, it’s fine to test your specific change locally and make a PR. Keep reading for an explanation of how to run full tests for googledrive.
A token is put into force at the beginning of a test run by the first few lines of tests/testthat/helper.R.
For speed reasons, the googledrive tests expect to find certain pre-existing files and folders, i.e. we don’t do full setup and tear down on each run. You do setup at the beginning of your googledrive development and leave these files in place while you work. When you’re done, e.g., when your PR is complete, you can clean up these files. Each test run also creates and destroys files, both locally and on Drive, but that is different and not what we’re talking about here.
tests/testthat/driver.R to extract and aggregate the current setup and clean code across all test files.
tests/testthat/all-test-clean.R. Inspect them.
When you are truly ready to perform setup or clean, edit the code to set the
CLEAN variable to
TRUE instead of
FALSE. This friction is intentional, so you don’t accidentally create or delete lots of Drive files without meaning to.
all-test-setup.R with the Knit button in RStudio or like so:
You could also just source it, but it’s nice to have a report that records what actually happened.
You should now be able to run the tests via Build > Test Package or Build > Check Package in RStudio or via
You can leave the setup in place for as long as you’re working on googledrive, i.e. you don’t need to do this for every test run. In fact, that is the whole point!
When your googledrive development is over, render the clean script:
Again, read the report to look over what happened, in case anything was trashed that should not have been (btw, let us know about that so we can fix!). Once you’re satisfied that your own files were not touched, you can
drive_empty_trash() to truly delete the test files.
If you’re going to add or modify tests, follow these conventions:
# ---- clean ----or
# ---- tests ----. This is what enables the
driver.Rscript to isolate the setup or cleaning code. Don’t break that.
# ---- nm_fun ----chunk to define naming functions used in that test file (see existing files for examples). Always use one of these functions to generate file names. Use
nm_()for test files that persist. Use
me_()for ephemeral test files that are created and destroyed in one test run.
Example and structure of a self-documenting name for a persistent test file:
Example and structure of a self-documenting name for an ephemeral test file:
Note that the current user is appended! This is so that concurrent test runs do not attempt to edit the same files.
googledrive is checked on a large matrix of R versions and operating systems via GitHub Actions. We use codecov to track the test coverage. In general, the package is subjected to
R CMD check, unit tests, and test coverage analysis after every push to GitHub. For internal branches, an encrypted service account token is available on GHA, so tests against the Drive API can be run.
Things are a bit different for pull requests from outside contributors, however. These PRs do not have access to the encrypted tokens, therefore many tests must be skipped. The PR will still be vetted via
R CMD check and tests that do not call the Drive API can still be run. After you make a PR, it’s a good idea to check back after a few minutes to see all of these results. If there are problems, read the log and try to correct the problem proactively. We “squash and merge” most pull requests, internal or external, so don’t agonize over the commit history.
Please note that the googledrive project is released with a Contributor Code of Conduct. By contributing to this project you agree to abide by its terms.