R CMD check locally for you. It’s a good idea to do that before you touch anything, so you have a baseline.NAMESPACE or .Rd files by hand. More below.docs/. We’ll take care of that.#15 syntax 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 closes #44 or 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.md with a concise description of the change, if it’s something a user would want to know when updating the package. dplyr’s NEWS.md is 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_find(), drive_upload(), 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. These are functions like generate_request() and process_response(). 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.
We use roxygen2, specifically with the Markdown syntax, to create NAMESPACE and all .Rd files. All edits to documentation should be done in roxygen comments above the associated function or object.
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 \dontrun{}.
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 require authorization and that rely on the existence of specific files and folders. Therefore, to fully test googledrive, you’ll have to store a token in a specific place and you’ll have to do some setup. We’ve tried to make it fairly easy to do this setup and to clean up those files when you’re done.
TL;DR with more detail below:
## store an OAuth token
## TO DO: update this when dust settles re: gargle and service token!
token <- drive_auth(reset = TRUE, cache = FALSE)
saveRDS(token, rprojroot::find_testthat_root_file("testing-token.rds"))
## gather all the test setup and clean code from individual test files
source(rprojroot::find_testthat_root_file("driver.R"))
## leaves behind:
## * all-test-setup.R
## * all-test-clean.R
## "activate" by editing, e.g., SETUP <- TRUE vs SETUP <- FALSE
## source or, I prefer, render the setup script
rmarkdown::render(rprojroot::find_testthat_root_file("all-test-setup.R"))
## do all development work that requires tests HERE
## source or, I prefer, render the clean script
rmarkdown::render(rprojroot::find_testthat_root_file("all-test-clean.R"))Obtain a new, non-caching token via browser flow.
Double-check that the user associated with the token is what you want.
Write this token to file, to the location expected by googledrive’s tests.
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-setup.R and tests/testthat/all-test-clean.R. Inspect them.SETUP or 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 devtools::test().
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.R script 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 the current R release on Windows, via AppVeyor, and on several versions of R on Linux, via Travis CI. 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. There are encrypted OAuth tokens on both AppVeyor and Travis CI, 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.