|
| 1 | +## This package |
| 2 | + |
| 3 | +<!-- Insert package-specific content here. use_tidy_agents() will preserve this section when updating the rest of the file. --> |
| 4 | + |
| 5 | +## Package development |
| 6 | + |
| 7 | +### Key commands |
| 8 | + |
| 9 | +(All these functions have been optimized for agentic use, so they can be called directly without other arguments.) |
| 10 | + |
| 11 | +```R |
| 12 | +# Executing code |
| 13 | +devtools::load_all() |
| 14 | +code |
| 15 | + |
| 16 | +# Tests |
| 17 | +devtools::test() # all tests |
| 18 | +devtools::test(filter = "^{name}") # tests for files starting with {name} |
| 19 | +devtools::test_active_file("R/{name}.R") # tests for R/{name}.R |
| 20 | +devtools::test_active_file("R/{name}.R", desc = 'blah') # single test with exact description "blah" (no regexp) |
| 21 | + |
| 22 | +# Test coverage |
| 23 | +devtools::test_coverage() # all files |
| 24 | +devtools::test_coverage_active_file("R/{name}.R") # coverage for R/{name}.R from tests in tests/testthat/test-{name}.R |
| 25 | + |
| 26 | +# Documentation |
| 27 | +devtools::document() # redocument package |
| 28 | +pkgdown::check_pkgdown() # check website |
| 29 | + |
| 30 | +# Run complete R CMD check |
| 31 | +devtools::check() |
| 32 | +``` |
| 33 | + |
| 34 | +### Running R |
| 35 | + |
| 36 | +There are three possible ways to run code, listed in rough order of desirability: |
| 37 | + |
| 38 | +- If you're running inside Posit Assistant or otherwise have an |
| 39 | + `executeCode()` tool available, use it to run code in a session that the |
| 40 | + user can also interact with. |
| 41 | + |
| 42 | +- Otherwise, if an R REPL (e.g. `mcp__r__repl` or `btw::run_r`) is |
| 43 | + available, use that. Note that `mcp__r__repl` uses a sandbox that blocks |
| 44 | + network requests and reads/writes outside of the current directory. |
| 45 | + |
| 46 | +- Otherwise, use `Rscript -e "code"`. |
| 47 | + |
| 48 | +### Code style |
| 49 | + |
| 50 | +- Follow the tidyverse style guide |
| 51 | +- Always run `air format .` after generating code. |
| 52 | +- Use the base pipe operator (`|>`), not the magrittr pipe (`%>%`). |
| 53 | +- Use `\() ...` for single-line anonymous functions. For all other cases, use `function() {...}`. |
| 54 | + |
| 55 | +### Test style |
| 56 | + |
| 57 | +- Tests for `R/{name}.R` go in `tests/testthat/test-{name}.R`. |
| 58 | +- All new code should have an accompanying test. |
| 59 | +- If there are existing tests, place new tests next to similar existing tests. |
| 60 | +- Strive to keep your tests minimal with few comments. |
| 61 | +- Never put code in a `test-{name}.R` file outside of a `test_that()` block. Instead, use `tests/testthat/helper.R` or `tests/testthat/helper-{name}.R`. |
| 62 | +- Avoid `expect_true()` and `expect_false()` in favor of a specific expectation with a better failure message. A few expectations in newer releases that you might not know about are `expect_all_true()`, `expect_all_equal()`, and `expect_r6_class()`. |
| 63 | +- When testing errors and warnings: |
| 64 | + - Only use `expect_error()` or `expect_warning()` if the error or warning has a known class. |
| 65 | + - Generally, prefer `expect_snapshot(error = TRUE)` for errors and `expect_snapshot()` for warnings because these allow the user to review the full text of the output. |
| 66 | +- Avoid the `.package` argument to `local_mocked_bindings()`; this modifies the namespace of another package, which is not good practice. Instead create a mockable version of the function in the current package. See `?local_mocked_bindings` for more details. |
| 67 | + |
| 68 | +### Documentation |
| 69 | + |
| 70 | +- Every user-facing function should be exported and have roxygen2 documentation. |
| 71 | +- Internal functions should not have roxygen documentation. |
| 72 | +- Wrap roxygen2 comments to 80 characters. |
| 73 | +- Whenever you add a new (non-internal) documentation topic, also add the topic to `_pkgdown.yml`. |
| 74 | +- Always re-document the package after changing a roxygen2 comment. |
| 75 | +- Use `pkgdown::check_pkgdown()` to check that all topics are included in the reference index. |
| 76 | + |
| 77 | +### `NEWS.md` |
| 78 | + |
| 79 | +- Every user-facing change should be given a bullet in `NEWS.md`. |
| 80 | +- Changes that shouldn't get a bullet: |
| 81 | + - Small documentation changes. |
| 82 | + - Internal refactorings. |
| 83 | + - Fixes to bugs introduced in the current dev version. |
| 84 | +- Each bullet should briefly describe the change to the end user and mention the related issue in parentheses. |
| 85 | +- A bullet can consist of multiple sentences but should not contain any newlines (i.e. DO NOT line wrap). |
| 86 | +- If the change is related to a function, put the name of the function early in the bullet. |
| 87 | +- If the change is related to an issue, include the issue number in parentheses. |
| 88 | +- Only include a GitHub username if the PR was created by someone who isn't an author. |
| 89 | +- Order bullets alphabetically by function name. Put all bullets that don't mention function names at the beginning. |
| 90 | + |
| 91 | +## Specialized skills |
| 92 | + |
| 93 | +- Do you need to deprecate a function or argument? Read the output of `usethis::learn_tidy_skill("deprecate")`. |
| 94 | +- Are you adding input checking to an existing function or writing a new exported function? Read the output of `usethis::learn_tidy_skill("arg-checking")`. |
| 95 | + |
| 96 | +## Git |
| 97 | + |
| 98 | +- If the user asks you to commit, use markdown in the commit message, and don't line wrap. |
| 99 | +- If the commit fixes an issue, include `Fixes #num.` on its own line. |
| 100 | +- Only push when the user explicitly requests it. |
| 101 | + |
| 102 | +## Writing |
| 103 | + |
| 104 | +- Use sentence case for headings. |
| 105 | +- Use US English. |
| 106 | + |
| 107 | +### Proofreading |
| 108 | + |
| 109 | +If the user asks you to proofread a file, act as an expert proofreader and editor with a deep understanding of clear, engaging, and well-structured writing. |
| 110 | + |
| 111 | +Work paragraph by paragraph, always starting by making a TODO list that includes individual items for each top-level section. |
| 112 | + |
| 113 | +Fix spelling, grammar, and other minor problems without asking the user. Label any unclear, confusing, or ambiguous sentences with a FIXME comment. |
| 114 | + |
| 115 | +Only report what you have changed. |
0 commit comments