1# usethis 2.0.1 2 3* All functions that require a package now ask you if you'd like to install it. 4 5* Added `edit_template()` for opening and creating files in `inst/templates` 6 (for use with `use_template()`) (@malcolmbarrett, #1319). 7 8* `use_article()` now creates the file in the `vignettes/articles/` (#548). 9 10* `use_lifecycle()` has been updated for changes in our lifecycle workflow 11 (#1323). 12 13* `use_tidy_pkgdown()` has been renamed to `use_pkgdown_github_pages()` since 14 the function is useful for anyone who wants to automatically publish to GitHub 15 pages, not just the tidyverse team (#1308). 16 17* `use_release_issue()` includes a bunch of minor improvements. Most 18 importantly, for initial CRAN release we now include a number of common 19 things that CRAN checks for that aren't in `R CMD check`. 20 21* `use_readme_rmd()`, `use_readme_md()`, `use_tidy_contributing()`, and 22 `use_tidy_support()` use updated logic for determining the `OWNER/REPO` spec 23 of the target repo (#1312). 24 25# usethis 2.0.0 26 27## Adoption of gert and changes to Git/GitHub credential handling 28 29Usethis has various functions that help with Git-related tasks, which break down into two categories: 30 311. Git tasks, such as clone, push, and pull. These are things you could do with 32 command line Git. 331. GitHub tasks, such as fork, release, and open an issue or pull request. These 34 are things you could do in the browser or with the GitHub API. 35 36We've switched from git2r to the gert package for Git operations (<https://docs.ropensci.org/gert/>). We continue to use the gh package for GitHub API work (<https://gh.r-lib.org>). 37 38The big news in this area is that these lower-level dependencies are getting better at finding Git credentials, finding the same credentials as command line Git (and, therefore, the same as RStudio), and finding the same credentials as each other. This allows usethis to shed some of the workarounds we have needed in the past, to serve as a remedial "credential valet". 39 40Under the hood, both gert and gh are now consulting your local Git credential store, when they need credentials. At the time of writing, they are using two different even-lower-level packages to do this: 41 42* gert uses the credentials package (<https://docs.ropensci.org/credentials/>) 43* gh uses the gitcreds package (<https://gitcreds.r-lib.org/>) 44 45Even now, gert and gh should discover the same credentials, at least for github.com. In the future, these two packages may merge into one. 46 47Git/GitHub credential management is covered in a new article: 48[Managing Git(Hub) Credentials](https://usethis.r-lib.org/articles/articles/git-credentials.html) 49 50The main user-facing changes in usethis are: 51 52* usethis should discover and use the same credentials as command line Git. 53* usethis should be able to work with any GitHub deployment. While github.com is the default, GitHub Enterprise deployments are fully supported. The target GitHub host is determined from the current project's configured GitHub remotes, whenever possible. 54 55As a result, several functions are deprecated and several other functions have some deprecated arguments. 56 57* Deprecated functions: 58 - `use_git_credentials()` 59 - `git_credentials()` 60 - `github_token()` 61* Functions with (deprecated arguments): 62 - `create_from_github()` (`auth_token`, `credentials`) 63 - `use_github()` (`auth_token`, `credentials`) 64 - `use_github_links()` (`host`, `auth_token`) 65 - `use_github_labels()` (`repo_spec`, `host`, `auth_token`) 66 - `use_tidy_labels()` (`repo_spec`, `host`, `auth_token`) 67 - `use_github_release()` (`host`, `auth_token`) 68 69The switch to gert + credentials should eliminate most credential-finding fiascos. Gert also takes a different approach to wrapping libgit2, the underlying C library that does Git operations. The result is more consistent support for SSH and TLS, across all operating systems, without requiring special effort at install time. More users should enjoy Git remote operations that "just work", for both SSH and HTTPS remotes. There should be fewer "unsupported protocol" errors. 70 71## GitHub remote configuration 72 73Usethis gains a more formal framework for characterizing a GitHub remote configuration. We look at: 74 75 * Which GitHub repositories `origin` and `upstream` point to 76 * Whether you can push to them 77 * How they relate to each other, e.g. fork-parent relationship 78 79This is an internal matter, but users will notice that usethis is more clear about which configurations are supported by various functions and which are not. The most common configurations are reviewed in a [section of Happy Git](https://happygitwithr.com/common-remote-setups.html). 80 81When working in a fork, there is sometimes a question whether to target the fork or its parent repository. For example, `use_github_links()` adds GitHub links to the URL and BugReports fields of DESCRIPTION. If someone calls `use_github_links()` when working in a fork, they probably want those links to refer to the *parent* or *source* repo, not to their fork, because the user is probably preparing a pull request. Usethis should now have better default behaviour in these situations and, in some cases, will present an interactive choice. 82 83## Default branch 84 85There is increasing interest in making the name of a repo's default branch configurable. Specifically, `main` is emerging as a popular alternative to `master`. Usethis now discovers the current repo's default branch and uses that everywhere that, previously, we had hard-wired `master`. 86 87`git_branch_default()` is a newly exported function that is also what's used internally. 88 89`use_course()`, `use_zip()`, and `create_download_url()` all have some support for forming the URL to download a `.zip` archive of a repo, based on a repo specification (e.g. `OWNER/REPO`) or a browser URL. These helpers now form a URL that targets `HEAD` of the repo, i.e. the default branch. 90 91## Changes to Git/GitHub functionality 92 93The default Git protocol is now "https" and we no longer provide an interactive choice, by default, in interactive sessions. As always, a user can express a preference for "ssh" in individual function calls, for an R session via `use_git_protocol()`, and for all R sessions via the `usethis.protocol` option (#1262). 94 95`pr_resume()` is a new function for resuming work on an existing local PR branch. It can be called argument-less, to select a branch interactively. 96 97`pr_fetch()` can also be called with no arguments, to select a PR interactively. 98The `owner` argument is replaced by `target`, with a choice of the source (default) or primary repo. 99 100`pr_forget()` is a new function for abandoning a PR you initiated locally or fetched from GitHub. It only does local clean up and, for example, doesn't delete a remote branch or close a PR (#1263). 101 102`pr_view()` can now be called with no arguments. If the current branch is associated with an open PR, we target that and, otherwise, we offer an interactive selection. 103 104`pr_finish()` deletes the remote PR branch if the PR has been merged and the current user has the power to do so, i.e. an external contributor deleting their own branch or a maintainer deleting a branch associated with an internal PR (#1150). It no longer errors if the PR branch has already been deleted (#1196). 105 106`pr_pull_upstream()` is renamed to `pr_merge_main()` to emphasize that it merges the **main** line of development into the current branch, where the main line of development is taken to mean the default branch, as reported by `git_branch_default()`, of the source repo, which could be either `upstream` or `origin`, depending on the situation. 107 108`create_from_github()` will only create a read-only clone, due to lack of a GitHub personal access token, if explicitly directed to do so via `fork = FALSE`. 109 110`create_from_github()` and `use_tidy_thanks()` accept browser and Git URLs as the `repo_spec` argument, to be friendlier to copy/paste. When a URL is passed, the `host` is also extracted from it. 111 112`create_github_token()` is a new name for the function previously known as `browse_github_token()` and `browse_github_pat()`. 113 114`issue_close_community()` and `issue_reprex_needed()` are two new functions for maintainers who process lots of GitHub issues. They automate canned replies and actions, e.g. labelling or closing (#940). 115 116GitHub Actions is the preferred platform for continuous integration, because that is what the tidyverse team currently uses and maintains. Functions related to Travis-CI and AppVeyor are soft-deprecated to raise awareness about this change and to make it clear that, if substantial maintenance becomes necessary, we may elect to retire the function (#1169). 117 118`browse_github_actions()` is a new function to open the Actions page of the respective repo on GitHub, similar to existing `browse_*()` functions (@pat-s, #1102). 119 120`use_github_pages()` is a new function to activate or reconfigure the GitHub Pages site associated with a repository (#224). 121 122`use_tidy_pkgdown()` implements the complete pkgdown configuration used by the tidyverse team (#224). 123 124`pr_sync()` is defunct and can be replicated by calling `pr_pull()`, `pr_merge_main()`, then `pr_push()`. 125 126## Licensing improvements 127 128All `use_*_license()` functions now work for projects, not just packages. 129 130`use_apl2_license()` (not `use_apache_license()`) and `use_gpl3_license()` no longer modify the license text (#1198). 131 132`use_mit_license()` now sets the default copyright holder to "{package} authors". This makes it more clear that the copyright holders are the contributors to the package; unless you are using a CLA there is no one copyright holder of a package (#1207). 133 134New `use_gpl_license()` and `use_agpl_license()` make it easier to pick specific versions of the GPL and AGPL licenses, and to choose whether or not you include future versions of the license. Both default to version 3 (and above). 135 136New `use_proprietary_license()` allows your package to pass R CMD check while making it clear that your code is not open source (#1163). Thanks to @atheriel for the blog post suggesting the wording: https://unconj.ca/blog/copyright-in-closed-source-r-packages-the-right-way.html 137 138`use_lgpl_license()` now uses version 3 (and above), and gains new `version` and `include_future` argument to control which version is used. 139 140`use_gpl3_license()`, `use_agpl3_license()` and `use_apl2_license()` have been deprecated in favour of the new `version` argument to `use_gpl_license()`, `use_agpl_license()` and `use_apache_license()`. 141 142The `name` argument to `use_mit_license()` has been changed to `copyright_holder` to make the purpose more clear. The `name` argument has been removed from all other license functions because it is not needed; no other license makes an assertion about who the copyright holder is. 143 144## RStudio preferences 145 146usethis is now fully cognizant of the [changes to RStudio preferences](https://blog.rstudio.com/2020/02/18/rstudio-1-3-preview-configuration/) in RStudio 1.3: 147 148`edit_rstudio_snippets()` looks in the new location, and if you have snippets in the old location, will automatically copy them to the new location (#1204) 149 150New `edit_rstudio_prefs()` opens RStudio preferences file for editing (#1148). 151 152`use_blank_slate()` can now configure your global, i.e. user-level, RStudio preference, in addition to project-level (#1018). 153 154## Other changes 155 156`browse_package()` and `browse_project()` are new functions that let the user choose from a list of URLs derived from local Git remotes and DESCRIPTION (local or possibly on CRAN) (#1113). 157 158The legacy `"devtools.desc"` option is no longer consulted when populating a new DESCRIPTION file. You must use the `"usethis.description"` now (#1069). 159 160`use_dev_package()` gains a `remote` parameter to allow you to specify the remote. The existing behaviour, which adds an `OWNER/REPO` GitHub remote, remains the default (#918, @ijlyttle). 161 162`use_cpp11()` is a new function to set up an R package to use cpp11. 163 164`create_package(roxygen = FALSE)` once again writes a valid NAMESPACE file (and also has no Roxygen* fields in DESCRIPTION) (#1120). 165 166`create_package()`, `create_project()`, `create_from_github()`, and `proj_activate()` work better with relative paths, inside and outside of RStudio (#1122, #954). 167 168`use_testthat()` gains an edition argument to support testthat v3.0.0 169 (#1185) 170 171`use_version()` now updates `src/version.c` if it exists and contains a line matching `PKG_version = "x.y.z";`. 172 173usethis has been re-licensed as MIT (#1252, #1253). 174 175## Dependency changes 176 177New Imports: gert, jsonlite (was already an indirect dependency), lifecycle, rappdirs 178 179No longer in Imports: git2r, rematch2 180 181# usethis 1.6.3 182 183Patch release to refactor usage of withr in the tests for forward compatibility with an upcoming withr release. All changes are within the usethis tests. 184 185# usethis 1.6.1 186 187Patch release to align some path handling internals with an update coming in the fs package. 188 189* `use_github_links()` is a bit more clever about remotes (e.g. `origin` 190 vs. `upstream`), which makes it easier to make a PR that adds GitHub links for 191 a package you've forked. 192 193* `use_pkgdown()` now `.gitignore`s the destination directory and only adds the 194 destination directory to the config file if it departs from the default 195 (which is `docs/`). 196 197* `use_tidy_ci()` is now deprecated in favour of `use_tidy_github_actions()` 198 (#1098). 199 200* `use_github_action_check_standard()` is a new intermediate workflow that 201 checks on more platforms than `_release`, but is less exhaustive than `_full` 202 (@jimhester). 203 204* `create_tidy_package()` now uses an MIT license (@topepo, #1096). 205 206# usethis 1.6.0 207 208## GitHub actions 209 210* New `use_github_actions()`, `use_github_action_check_release()`, 211 `use_github_action_check_full()`, `use_github_action_pr_commands()`, 212 to set up GitHub Actions for a package (@jimhester). 213 214* We now recommend GitHub Actions instead of Travis-CI or AppVeyor, and strongly 215 recommend upgrading your packages. 216 217* Fix `use_github_action()` URL parameter to ensure custom URLs are allowed. 218 (@coatless, #1065). 219 220## Package creation 221 222* `create_package()` gains a `roxygen` argument. If `TRUE` (the default), 223 it adds a `RoxygenNote` field to the `DESCRIPTION` (which means the first run 224 of `devtools::check()` will re-document the package, #963), and creates an 225 empty `NAMESPACE` (which means you'll always need an explicit `@export` 226 if you want to export functions, #927). It also turns markdown processing 227 on by default (#911). 228 229* `use_rstudio()` now sets the `LineEndingConversion` to `Posix` so that 230 packages created using usethis always use LF line endings, regardless of 231 who contributes to them (#1002). 232 233* In the `usethis.description` option, you can now set `Authors@R = person()` 234 directly, without having to wrap in additional layer of quotes. If setting 235 this in your `.Rprofile`, you'll need to use `utils::person()` since the utils 236 package isn't loaded until after your profile is executed. 237 238## PR helpers 239 240* A new article [Pull request helpers](https://usethis.r-lib.org/articles/articles/pr-functions.html) 241 demonstrates how to use the `pr_*()` functions (@mine-cetinkaya-rundel, #802). 242 243* `pr_finish()` checks that you don't have any local changes (#805), and can 244 optionally finish any PR, not just the current (#1040). 245 246* `pr_pause()` and `pr_fetch()` now automatically pull to get latest changes 247 (#959, #960) and refresh RStudio's git pane (#706). 248 249* `pr_push()` now works for a repository with no open pull requests 250 (@maurolepore, #990). 251 252* `pr_pull()` gives more information about which files have merge conflicts 253 and automatically opens conflicted files for editing (#1056). 254 255## Other new features 256 257* New `rename_files()` makes it easy to rename paired `R/` and `test/` files 258 (#784). 259 260* New `ui_silence()` makes it easier to selectively silence some UI output. 261 262* New `use_agpl3_license()` (@pachamaltese, #870). 263 264* New `use_data_table()` to set up a package for Import-ing `data.table` 265 (@michaelchirico, #897). 266 267* `use_latest_dependencies()` replaces `use_tidy_version()` as the new name 268 better reflect its usage (#771). 269 270* New `use_lifecycle()` helper to import the lifecycle badges for functions and 271 arguments in your package. Learn more at <https://lifecycle.r-lib.org/>. 272 273* `use_release_issue()` will include additional bullets if your package 274 includes `release_bullets()` function which returns a character 275 vector (and the package has been loaded with `load_all()`) (#941). 276 277## Minor improvements and bug fixes 278 279* When writing files, usethis now respects line endings. Default line endings 280 are taken from the `.Rproj` file (if available), otherwise the `DESCRIPTION`, 281 otherwise the first file found in `R/`, then all else failing to your 282 platform default (#767). It should do a better job of preserving UTF-8 files 283 on windows (#969). 284 285* `browse_github()` now always goes to the canonical GitHub site: 286 `https://github.com/user/repo`. This is slightly worse than the current 287 behaviour but makes the function more consistent across packages, and 288 considerably simplifies the implementation. 289 290* `browse_circle()` opens the project dashboard on Circle CI. 291 292* `create_download_url()` is a new helper for making "ZIP file download" 293 URLs suitable for use with `use_course()` and `use_zip()`, starting with the 294 URLs that mere mortals can usually get their hands on in a browser 295 (@fmichonneau, #406). 296 297* `create_package()` no longer fails partway through if you have a malformed 298 `usethis.description` option (#961). 299 300* `create_package()` will now create a package in a symlink to a directory 301 (#794). 302 303* `create_package()` and `use_description()` gain a `check_name` argument to 304 control whether to check for package names invalid for CRAN (@noamross, #883). 305 306* `edit_file()` and `use_test()` gain an `open` parameter that allows you to 307 control whether or not the function is opened for editing by the user (#817). 308 309* `edit_rstudio_snippets()` makes it more clear which snippet types are 310 allowed and that user's snippets mask the built-in snippets (@GegznaV, #885). 311 312* `git_sitrep()` now reports project-specific user name and email, if set 313 (#837), and email(s) associated with your GitHub account (@dragosmg, #724). 314 315* `ui_yeah()` and `ui_nope()` allow you to override the default "yes" and 316 "no" strings and to opt-out of shuffling (@rundel, #796). 317 318* `use_circleci()` uses correct delimiters in template (@jdblischak, #835). 319 320* `use_circleci_badge()` is now exported (@pat-s, #920). 321 322* `use_code_of_conduct()` now generates an absolute link to code of conduct on 323 pkgdown website or original source to avoid R CMD check issues (#772). 324 325* `use_course()` and `use_zip()` are now equipped with some retry capability, 326 to cope with intermittent failure or the need for a longer connect timeout 327 (#988). 328 329* `use_data()` automatically bumps R dependency to 2.10 (#962). 330 331* `use_data_raw()` template quotes the dataset name correctly 332 (#736, @mitchelloharawild). 333 334* `use_description_defaults()` now shows the default fields combined with 335 any options that you have set. 336 337* `use_dev_package()` now supports packages installed from any remote type, 338 not just GitHub (@antoine-sachet, #1071). 339 340* `use_git()` will now create initial commit if needed (#852). 341 342* `use_github_release()` no longer fails if you have no news bullets (#1048). 343 344* `use_github_release()` now tags the latest local commit instead of the latest 345 remote commit on the default branch (@davidchall, #1029). 346 347* `use_gpl3_license()` now completes the license by providing additional 348 information in a file named LICENSE, just like `use_mit_license()` and 349 friends (@Cervangirard, #683). 350 351* `use_logo()` now generates the correct href if the pkgdown `url` is set 352 (@mitchelloharawild, #986). 353 354* `use_make()` gains missing closing parenthesis (@ryapric, #804). 355 356* `use_markdown_template()` no longer uses an unexported function in its 357 default arguments (@fmichonneau, #761). 358 359* `use_testthat()` and `use_test()` now work in projects, not just packages 360 (#1017). 361 362* `use_test()` works on Windows when called without arguments (#901). 363 364* `use_tidy_issue_template()` uses current github format (@Maschette, #756). 365 366* `use_travis()`, `use_travis_badge()`, and `browse_travis()`, now default 367 to `ext = "com"` since travis-ci.com is now recommended it over travis-ci.org 368 (@riccardoporreca, #1038). 369 370* `use_release_issue()` reminds you to re-generate `README.md`, 371 if needed (#767). 372 373* `use_r()` and `use_test()` throw a clear error if multiple names are provided 374 (@strboul, #862). 375 376* `use_rcpp()` and `use_c()` now ensure `src/` contains at least one `.cpp` or 377 `.c` placeholder file, so that the package can be built (@coatless, #720). 378 379* `usethis.destdir` is a new option that is consulted when deciding where to 380 put a new folder created by `use_course()` or `create_from_github()` 381 (@malcolmbarrett, #1015). 382 383* `use_lifecycle()` no longer adds the lifecycle package to the DESCRIPTION 384 file. With the new roxygen markdown syntax for including badges, lifecycle has 385 become a build-time dependency. 386 387## Dependency changes 388 389New Imports: cli, rematch2, rlang. 390 391gh minimum version is bumped to v.1.1.0, due to changed behaviour around requests that return nothing. 392 393clisymbols is removed from Imports. 394 395# usethis 1.5.1 396 397This is a patch release with various small features and bug fixes. 398 399## Using the pipe `%>%` or the tidy eval toolkit in your package 400 401* The templates used by `use_pipe()` and `use_tidy_eval()` use a more robust 402 form of cross-reference links, linking to files rather than topics. This 403 should silence some warnings seen on Windows at install time 404 (#730, #731 @jmgirard). 405 406* `use_pipe()` gains a logical `export` argument, so it can do the setup 407 necessary to use the pipe operator when it is re-exported 408 (`export = TRUE`, which is the default and preserves the previous behaviour) 409 and when it is not (`export = FALSE`) (#783). 410 411## Git, GitHub, and pull requests 412 413* `use_github()` removes newline `\n` characters from the description that 414 can cause the initial push to fail (#493, @muschellij2). 415 416* `git_sitrep()` gives better feedback if we can't validate the GitHub PAT 417 (#725, @ijlyttle). 418 419* `create_from_github()` sets remote tracking branch of `master` to 420 `upstream/master`, when it creates (and clones) a fork (#792). 421 422* `pr_pause()` can switch back to master even if there is no remote tracking 423 branch (#715, @cderv). 424 425## Build tools and continuous integration 426 427* `use_tidy_ci()` is updated for R 3.6, meaning that R 3.2 is the oldest version 428 of R supported through proactive testing. 429 430* `use_make()` and `use_jenkins()` add a Makefile and Jenkinsfile, respectively 431 (#501, @ryapric). 432 433* `use_circleci()` creates a `.circleci/config.yaml` config file for CircleCI 434 (#703, @jdblischak). 435 436## Other 437 438* `use_zip()` is a new variant of `use_course()` that downloads and unpacks a 439 ZIP file, with less pedantic behaviour re: the destination directory. Both 440 functions now also work for ZIP files with MIME type 441 `"application/x-zip-compressed"` (#573). 442 443* `use_version()` can detect `"(development version)"` in a NEWS header and 444 update it with an actual version (#768, @DavisVaughan). 445 446## Dependency changes 447 448R 3.1 is no longer explicitly supported or tested. Our general practice is to support the current release (3.6, at time of writing), devel, and the 4 previous versions of R (3.5, 3.4, 3.3, 3.2). 449 450fs minimum version is stated to be v1.3.0. 451 452glue minimum version is stated to be v1.3.0. 453 454# usethis 1.5.0 455 456## Git, GitHub (and GitLab) 457 458usethis gains several functions to inspect and manipulate the Git situation for the current project = repository. We also provide more control and visibility 459into git2r's workings, especially around credentials (usethis uses git2r for all 460Git operations). 461 462* `git_sitrep()` lets you know what's up with your Git, git2r and GitHub 463 config (#328). 464 465* `git_vaccinate()` vaccinates your global (i.e. user-level) git ignore file. 466 It adds standard entries for R users, such as `.Rhistory` and `.Rdata`. This 467 decreases the chance that you commit and push files containing confidential 468 information (#469). 469 470* `git_remotes()` and `use_git_remote()` are new helpers to inspect or modify 471 Git remote URLs for the repo associated with the active project (#649). 472 473* `git_protocol()` + `use_git_protocol()` and `git_credentials()` + 474 `use_git_credentials()` are new helpers to summon or set Git transport 475 protocol (SSH or HTTPS) or git2r credentials, respectively. These functions 476 are primarily for internal use. Most users can rely on default behaviour. Use 477 these helpers to intervene if git2r isn't discovering the right credentials 478 (#653). usethis honors the `usethis.protocol` option, which allows you to 479 express a general preference for SSH vs. HTTPS. 480 481Other improvements and bug fixes: 482 483* `use_github()` tries harder but also fails earlier, with more informative 484 messages, making it less likely to leave the repo partially configured (#221). 485 486* `use_github()` and `create_from_github()` gain a `protocol` argument 487 (#494, @cderv). 488 489* `create_from_github()` pulls from upstream master in a fork (#695, @ijlyttle). 490 491* `use_release_issue()` creates a GitHub issue containing a release checklist, 492 reflecting the standard practices of the tidyverse team (#338). 493 494* `use_github_release()` creates a draft GitHub release using the entries in 495 `NEWS.md` (#137). 496 497* `use_gitlab_ci()` creates a `gitlab-ci.yaml` config file for GitLab CI 498 (#565, @overmar). 499 500* `use_git_config()` now invisibly returns the previous values of the 501 settings. 502 503* `use_github_labels()` has been rewritten be more flexible. You can now supply 504 a repo name, and `descriptions`, and you can set colours/descriptions 505 independently of creating labels. You can also `rename` existing labels 506 (#290). 507 508## GitHub pull requests 509 510We've added **experimental** functions to work with GitHub pull requests. They 511are aimed at both a maintainer (who may make, review, and modify pull 512requests) and a contributor (who may make or explore pull requests). 513 514* `git_sitrep()` includes a section at the end aimed at describing "pull request 515 readiness". Expect that to develop and expand. 516 517* `pr_init()`, `pr_fetch()`, `pr_push()`, `pr_pull()`, `pr_finish()`, and 518 `pr_view()` constitute the new family of helpers. They are designed to be 519 smart about the significance of remotes with the standard names of `origin` 520 and `upstream` and to facilitate both internal and external pull requests. 521 522## Partial file management 523 524usethis gains tooling to manage part of a file. This is currently used for 525managing badges in your README and roxygen import tags: 526 527* `use_badge()` and friends now automatically add badges if your README 528 contains a specially formatted badge block (#497): 529 530 ``` 531 <-- badge:start --> 532 <-- badge:end --> 533 ``` 534 535* `use_tibble()` and `use_rcpp()` automatically add roxygen tags to 536 to `{package}-package.R` if it contains a specially formatted namespace 537 block (#517): 538 539 ```R 540 ## usethis namespace: start 541 ## usethis namespace: end 542 NULL 543 ``` 544 545 Unfortunately this means that `use_rcpp()` no longer supports non-roxygen2 546 workflows, but I suspect the set of people who use usethis and Rcpp but 547 not roxygen2 is very small. 548 549## Extending and wrapping usethis 550 551* New `proj_activate()` lets you activate a project, either opening a new 552 RStudio session (if you use RStudio) or changing the working directory 553 (#511). 554 555* `proj_get()` and `proj_set()` no longer have a `quiet` argument. The 556 user-facing message about setting a project is now under the same control 557 as other messages, i.e. `getOption("usethis.quiet", default = FALSE)` (#441). 558 559* A new set of `ui_*()` functions makes it possible to give your own code 560 the same user interface as usethis (#308). All use the glue and crayon and 561 packages to power easy interpolation and formatting. There are four families 562 of functions: 563 564 * block styles: `ui_line()`, `ui_done()`, `ui_todo()`, `ui_oops()`, 565 `ui_info()`. 566 * conditions: `ui_stop()`, `ui_warn()`. 567 * questions: `ui_yeah()`, `ui_nope()`. 568 * inline styles: `ui_field()`, `ui_value()`, `ui_path()`, `ui_code()`. 569 570* `with_project()` and `local_project()` are new withr-style functions to 571 temporarily set an active usethis project. They make usethis functions easier 572 to use in an *ad hoc* fashion or from another package (#441). 573 574## Tidyverse standards 575 576These standards are (aspirationally) used by all tidyverse packages; you are 577welcome to use them if you find them helpful. 578 579* Call `use_tidy_labels()` to update GitHub labels. Colours are less 580 saturated, docs is now documentation, we use some emoji, and performance is 581 no longer automatically added to all repos (#519). Repo specific issues 582 should be given colour `#eeeeee` and have an emoji. 583 584* Call `use_logo()` to update the package logo to the latest specifications: 585 `man/figure/logo.png` should be 240 x 278, and README should contain 586 `<img src="man/figures/logo.png" align="right" height="139" />`. 587 This gives a nicer display on retina displays. The logo is also linked to the 588 pkgdown site if available (#536). 589 590* When creating a new package, use `create_tidy_package()` to start with a 591 package following the tidyverse standards (#461). 592 593* `NEWS.md` for the development version should use "(development version)" 594 rather than the specific version (#440). 595 596* pkgdown sites should now be built by travis and deployed automatically to 597 GitHub pages. `use_pkgdown_travis()` will help you set that up. 598 599* When starting the release process, call `use_release_issue()` to create a 600 release checklist issue (#338). 601 602* Prior to CRAN submission call `use_tidy_release_test_env()` to update the 603 test environment section in `cran-comments()` (#496). 604 605* After acceptance, try `use_github_release()` to automatically create a 606 release. It's created as a draft so you have a chance to look over before 607 publishing. 608 609* `use_vignette()` includes the a standard initialisation chunk with 610 `knitr::opts_chunk$set(comment = "#>", collapse = TRUE)` which should 611 be used for all Rmds. 612 613## New functions not already mentioned 614 615* `use_devtools()` (#624), `use_conflicted()` (#362), and `use_reprex()` (#465) 616 help add useful packages to your `.Rprofile`. 617 618* `use_partial_warnings()` helps the user add a standard warning block to 619 `.Rprofile` (#64). 620 621* `edit_r_buildignore()` opens `.Rbuildignore` for manual editing 622 (#462, @bfgray3). 623 624* `use_lgpl_license()` automates set up of the LGL license (#448, @krlmlr). 625 626* `use_ccby_license()` adds a CCBY 4.0 license (#547, @njtierney). 627 628* `use_rcpp_armadillo()` and `use_rcpp_eigen()` set up a package to use 629 RcppArmadillo or RcppEigen, respectively (#421, @coatless, @duckmayr). 630 631* `use_c("foo")` sets up `src/` and creates `src/foo.c` (#117). 632 633* `use_covr_ignore()` makes it easy to ignore files in test coverage (#434). 634 635* `use_pkgdown_travis()` helps you set up pkgdown for automatic build-and-deploy 636 from Travis-CI to GitHub Pages (#524). 637 638* `use_addin()` does setup for RStudio addins (#353, @haozhu233). 639 640* `use_tutorial()` creates a new interactive R Markdown tutorial, as implemented 641 by the [`learnr` package](https://rstudio.github.io/learnr/index.html) 642 (@angela-li, #645). 643 644* `use_article()` creates articles, vignettes that are automatically added to 645 `.Rbuildignore`. These appear on pkgdown sites, but are not included with the 646 package itself (#281). 647 648* `use_citation()` creates a basic `CITATION` template and puts it in the 649 right place (#100). 650 651## Other minor bug fixes and improvements 652 653* `write_union()` appends the novel `lines`, but does not remove duplicates 654 from existing lines (#583, @khailper). 655 656* `use_rcpp("foo")` now creates `src/foo.cpp` (#117). 657 658* `use_data()` gains a `version` argument and defaults to serialization format 659 version 2 (#675). 660 661* `use_data_raw()` accepts a name for the to-be-prepared dataset and opens a 662 templated R script (#646). 663 664* `browse_github()` now falls back to CRAN organisation (with a warning) if 665 package doesn't have its own GitHub repo (#186). 666 667* `create_*()` restore the active project if they error part way through, 668 and use `proj_activate()` (#453, #511). 669 670* `edit_r_profile()` and `edit_r_environ()` now respect environment variables 671 `R_PROFILE_USER` and `R_ENVIRON_USER`, respectively (#480). 672 673* `use_description()` once again prints the generated description (#287). 674 675* `use_description_field()` is no longer sensitive to whitespace, which 676 allows `use_vignette()` to work even if the `VignetteBuilder` field is 677 spread over multiple lines (#439). 678 679* `use_logo()` can override existing logo if user gives permission (#454). 680 It also produces retina appropriate logos by default, and matches the 681 aspect ratio to the <http://hexb.in/sticker.html> specification (#499). 682 683* `use_news_md()` will optionally commit. 684 685* `use_package()` gains a `min_version` argument to specify a minimum 686 version requirement (#498). Set to `TRUE` to use the currently installed 687 version (#386). This is used by `use_tidy_eval()` in order to require version 688 0.1.2 or greater of rlang (#484). 689 690* `use_pkgdown()` is now configurable with site options (@jayhesselberth, #467), 691 and no longer creates the `docs/` directory (#495). 692 693* `use_test()` no longer forces the filename to be lowercase (#613, @stufield). 694 695* `use_test()` will not include a `context()` in the generated file if used 696 with testthat 2.1.0 and above (the future release of testthat) (#325). 697 698* `use_tidy_description()` sets the `Encoding` field in `DESCRIPTION` 699 (#502, @krlmlr). 700 701* `use_tidy_eval()` re-exports `:=` (#595, @jonthegeek). 702 703* `use_tidy_versions()` has source argument so that you can choose to use 704 local or CRAN versions (#309). 705 706* `use_travis()` gains an `ext` argument, defaulting to `"org"`. Use 707 `ext = "com"` for `https://travis-ci.com` (@cderv, #500). 708 709* `use_version()` asks before committing. 710 711* `use_vignette()` now has a `title` argument which is used in YAML header 712 (in the two places where it is needed). The vignettes also lose the default 713 author and date fields (@rorynolan, #445), and the R Markdown starter material. 714 They gain a standard setup chunk. 715 716* `use_version("dev")` now creates a standard "(development version)" heading 717 in `NEWS.md` (#440). 718 719* `use_vignette()` now checks if the vignette name is valid (starts with letter 720 and consists of letters, numbers, hyphen, and underscore) and throws an error 721 if not (@akgold, #555). 722 723* `restart_rstudio()` now returns `FALSE` in RStudio if no project is open, 724 fixing an issue that caused errors in helpers that suggest restarting 725 RStudio (@gadenbuie, #571). 726 727## Dependency changes 728 729* withr moves from Suggests to Imports. 730 731* purrr and yaml are new in Imports. 732 733# usethis 1.4.0 734 735## File system 736 737All usethis file system operations now use the [fs](https://fs.r-lib.org) package (#177). This should not change how usethis functions, but users may notice these features of fs-mediated paths: 738 739 - Paths are "tidy", meaning `/` is the path separator and there are never multiple or trailing `/`. 740 - Paths are UTF-8 encoded. 741 - A Windows user's home directory is interpreted as `C:\Users\username` (typical of Unix-oriented tools, like Git and ssh; also matches Python), as opposed to `C:\Users\username\Documents` (R's default on Windows). Read more in [`fs::path_expand()`](https://fs.r-lib.org/reference/path_expand.html). 742 743## Extending or wrapping usethis 744 745These changes make it easier for others to extend usethis, i.e. to create workflow packages specific to their organization, or to use usethis in other packages. 746 747* `proj_path()` is newly exported. Use it to build paths within the active project. Like `proj_get()` and `proj_set()`, it is not aimed at end users, but rather for use in extension packages. End users should use [rprojroot](https://rprojroot.r-lib.org) or its simpler companion, [here](https://here.r-lib.org), to programmatically detect a project and 748build paths within it (#415, #425). 749 750 * `edit_file()`, `write_over()`, and `write_union()` are newly exported helpers. They are mostly for internal use, but can also be useful in packages that extend or customize usethis (#344, #366, #389). 751 752* `use_template()` no longer errors when a user chooses not to overwrite an existing file and simply exits with confirmation that the file is unchanged (#348, #350, @boshek). 753 754* `getOption("usethis.quiet", default = FALSE)` is consulted when printing user-facing messages. Set this option to `TRUE` to suppress output, e.g., to use usethis functions quietly in another package. For example, use `withr::local_options(list(usethis.quiet = TRUE))` in the calling function (#416, #424). 755 756## New functions 757 758* `proj_sitrep()` reports current working directory, the active usethis project, and the active RStudio Project. Call this function if things seem weird and you're not sure what's wrong or how to fix it. Designed for interactive use and debugging, not for programmatic use (#426). 759 760* `use_tibble()` does minimum setup necessary for a package that returns or exports a tibble. For example, this guarantees a tibble will print as a tibble (#324 @martinjhnhadley). 761 762* `use_logo()` resizes and adds a logo to a package (#358, @jimhester). 763 764* `use_spell_check()` adds a whitelist of words and a unit test to spell check package documentation during `R CMD check` (#285 @jeroen). 765 766## Other small changes and bug fixes 767 768* usethis has a new logo! (#429) 769 770* `use_course()` reports progress during download (#276, #380). 771 772* `use_git()` only makes an initial commit of all files if user gives explicit consent (#378). 773 774* `create_from_github()`: the `repo` argument is renamed to `repo_spec`, since it takes input of the form "OWNER/REPO" (#376). 775 776* `use_depsy_badge()` is defunct. The Depsy project has officially concluded and is no longer being maintained (#354). 777 778* `use_github()` fails earlier, with a more informative message, in the absence of a GitHub personal access token (PAT). Also looks for the PAT more proactively in the usual environment variables (i.e., GITHUB_PAT, GITHUB_TOKEN) (#320, #340, @cderv). 779 780* The logic for setting DESCRIPTION fields in `create_package()` and `use_description()` got a Spring Cleaning. Fields directly specified by the user take precedence, then the named list in `getOption("usethis.description")` is consulted, and finally defaults built into usethis. `use_description_defaults()` is a new function that reveals fields found in options and built into usethis. Options specific to one DESCRIPTION field, e.g. `devtools.desc.license`, are no longer supported. Instead, use a single named list for all fields, preferably stored in an option named `"usethis.description"` (however,`"devtools.desc"` is still consulted for backwards compatibility). (#159, #233, #367) 781 782## Dependency changes 783 784New Imports: fs, glue, utils 785 786No longer in Imports: backports, httr, rematch2, rmarkdown (moved to Suggests), styler (moved to Suggests) 787 788# usethis 1.3.0 789 790* usethis has a website: <https://usethis.r-lib.org> (#217). It includes an article with advice on system setup, for usethis and for R development more generally. 791 792* `edit_*()` functions now return the target path, invisibly (#255). 793 794* `edit_git_ignore(scope = "user")` prefers `~/.gitignore`, but detects an existing `~/.gitignore_global`, if it exists. If a new global gitignore file is created, it is created as `~/.gitignore` and recorded in user's git config as the `core.excludesfile` (#255). 795 796* `create_from_github()` gains several arguments and new functionality. The `protocol` argument lets user convey whether remote URLs should be ssh or https. In the case of "fork and clone", the original repo is added as `upstream` remote. It is now possible -- although rarely necessary -- to directly specify the GitHub PAT, credentials (in git2r form), and GitHub host (#214, #214, #253). 797 798* `use_github_labels()` can create or update the colour of arbitrary GitHub issue labels, defaulting to a set of labels and colours used by the tidyverse packages, which are now exposed via `tidy_labels()`. That set now includes the labels "good first issue" and "help wanted" (#168, #249). 799 800* `appveyor_info()` no longer reverses the repo's URL and image link. Corrects the markdown produced by `use_appveyor_badge()` (#240, @llrs). 801 802* `use_cran_badge()` uses an HTTPS URL for the CRAN badge image (#235, @jdblischak). 803 804* `create_package()` and `create_project()` return a normalized path, even if target directory does not pre-exist (#227, #228). 805 806## New functions 807 808* `use_git_config()` can set user's Git name or email, globally or locally in a project/repo (#267). 809 810* `browse_github_pat()` goes to the webpage where a GitHub user can create a personal access token (PAT) for the GitHub API. If the user configures a PAT, they can use functions like `create_from_github()` and `use_github()` to easily create and connect GitHub repos to local projects. (#248, #257, @jeroen, via @jennybc). 811 812* `use_version()` increments the version of the active package, including an interactive chooser. `use_dev_version()` is now a special case wrapper around this. (#188, #223, @EmilHvitfeldt). 813 814* `use_tidy_github()` creates a standard set of files that make a GitHub repository more navigable for users and contributors: an issue template, contributing guidelines, support documentation, and a code of conduct. All are now placed in a `.github/` subdirectory (#165, @batpigandme). 815 816* `use_bioc_badge` creates a Bioconductor badge that links to the build report (#271, @LiNk-NY). 817 818* `use_binder_badge()` creates a badge indicating the repository can be launched in an executable environment via [Binder](https://mybinder.org/) (#242, @uribo). 819 820# usethis 1.2.0 821 822## New functions 823 824* `use_course()` downloads a folder's worth of materials from a ZIP file, with deliberate choices around the default folder name and location. Developed for use at the start of a workshop. Helps participants obtain materials from, e.g., a DropBox folder or GitHub repo (#196). 825 826* `use_blank_slate()` provides a way to opt in to an RStudio workflow where the user's workspace is neither saved nor reloaded between R sessions. Automated for `scope = "project"`. Provides UI instructions for `scope = "user"`, for now (#139). 827 828* `use_tidy_style()` styles an entire project according to <https://style.tidyverse.org> (#72, #197 @lorenzwalthert). 829 830* GitHub conventions common to tidyverse packages are enacted by `use_tidy_contributing()`, `use_tidy_issue_template()`, and `use_tidy_support()` (@batpigandme, #143, #166). 831 832Other changes 833 834* New projects that don't exhibit other obvious criteria for being a "project" will include a sentinel, empty file named `.here`, so they can be recognized as a project. 835 836* Project launching and switching works on RStudio server (#115, #129). 837 838* `use_template()` is newly exported, so that other packages can provide 839templating functions using this framework (@ijlyttle #120). 840 841* `use_readme_rmd()` and `use_readme_md()` work, in a similar fashion, for projects that are and are not a package (#131, #135). 842 843* `use_readme_rmd()` once again creates a pre-commit git hook, to help keep `README.Rmd` and `README.md` in sync (@PeteHaitch #41). 844 845* Substantial increase in unit test coverage. 846 847# usethis 1.1.0 848 849## New helpers 850 851* `browse_github()`, `browse_github_issues()`, `browse_github_pulls()`, 852 `browse_cran()` and `browse_travis()` open useful websites related to 853 the current project or a named package. (#96, #103). 854 855* `create_from_github()` creates a project from an existing GitHub 856 repository, forking if needed (#109). 857 858* `use_cc0_license()` applies a CC0 license, particularly appropriate for data 859 packages (#94) 860 861* `use_lifecycle_badge()` creates a badge describing current stage in 862 project lifecycle (#48). 863 864* `use_pkgdown()` creates the basics needed for a 865 [pkgdown](https://github.com/r-lib/pkgdown) website (#88). 866 867* `use_r("foo")` creates and edit `R/foo.R` file. If you have a test file open, 868 `use_r()` will open the corresponding `.R` file (#105). 869 870* `use_tidy_versions()` sets minimum version requirement for all dependencies. 871 872## Bug fixes and improvements 873 874* `use_dev_version()` now correctly updates the `Version` field in a package 875 description file. (@tjmahr, #104) 876 877* `use_revdep()` now also git-ignores the SQLite database (#107). 878 879* `use_tidy_eval()` has been tweaked to reflect current guidance (#106) 880 881# usethis 1.0.0 882 883This is a new package that extracts out many functions that previously lived in devtools, as well as providing more building blocks so you can create your own helpers. As well as the many new helpers listed below, there are three main improvements to the package: 884 885* More support for general R projects, other than packages. 886* A notion of an "active" project that all commands operate on. 887* Refined output. 888 889usethis is gradually evolving towards supporting more general R "projects", not just packages. This is still a work in progress, so please let me know if you use a function that you think should work with projects but doesn't. You can also try out the new `create_project()` which creates a basic RStudio project. 890 891The concept of the working directory and the "base path" have been refined. Rather than using an argument to specify the active project, all `use_` functions now use a global active project setting, as returned by `proj_get()`. This is cached throughout a session, although it will be updated by `create_package()` and `create_project()`. You'll now get an clear error if you attempt to `use_something()` outside of a project, and `create_something()` will warn if you're trying to create inside an existing project. 892 893The output from all usethis commands has been reviewed to be informative but not overwhelming. usethis takes advantage of colour (using crayon and RStudio 1.1) to help chunk the output and clearly differentiate what you need to do vs. what has been done for you. 894 895## New functions 896 897* `use_apl2_license()` if you want to use the Apache 2.0 license. 898 899* `use_depsy_badge()` allows including a Depsy badge (@gvegayon, #68). 900 901* `use_dev_package()` works like `use_package()` but also adds the 902 repo to the `Remotes` field (#32). 903 904* `use_github_labels()` will automatically set up a standard set of labels, 905 optionally removing the default labels (#1). 906 907* `use_pipe()` creates a template to use magrittr's `%>%` in your package (#15). 908 909* `use_tidy_ci()` which sets up travis and codecov using the tidyverse 910 conventions (#14) 911 912* `use_tidy_description()` puts description fields in a standard order 913 and alphabetises dependencies. 914 915* `use_tidy_eval()` imports and re-exports the recommend set of tidy eval 916 helpers if your package uses tidy eval (#46). 917 918* `use_usethis()` opens your `.Rprofile` and gives you the code to copy 919 and paste in. 920 921## New edit functions 922 923A new class of functions make it easy to edit common config files: 924 925* `edit_r_profile_user()` opens `.Rprofile` 926* `edit_r_environ_user()` opens `.Renviron` 927* `edit_r_makevars_user()` opens `.R/Makevars` 928* `edit_git_config_user()` opens `.gitconfig` 929* `edit_git_ignore_user()` opens `.gitignore` 930* `edit_rstudio_snippets(type)` opens `~/R/snippets/{type}.snippets` 931 932## Updates 933 934* `use_coverage("codecov")` now sets a default threshold of 1% to try and 935 reduce false positives (#8). 936 937* `use_description()` now sets `ByteCompile: true` so you can benefit from 938 the byte compiler (#29) 939 940* The license functions (`use_mit_license()`, `use_apl2_license()`, and 941 `use_gpl3_license()`) save a copy of the standard license text in 942 `LICENSE.md`, which is then added to `.Rbuildignore`. This allows you 943 to follow standard licensing best practices while adhering to CRANs 944 requirements (#10). 945 946* `use_package_doc()` uses more a modern roxygen2 template that requires 947 less duplication. 948 949* `use_test()` will use the name of the currently open file in RStudio 950 if you don't supply an explicit name (#89). 951 952* `use_readme_rmd()` now puts images in `man/figures/` and no longer 953 adds to `.Rbuildgnore`. This ensures that the rendered `README.md` will 954 also work on CRAN (#16, #19). The first chunk now uses `include = FALSE` 955 and is named setup (#19). 956 957* `use_revdep()` creates structure for use with revdepcheck package, the 958 preferred way to run revdepchecks. (#33) 959 960## Building blocks 961 962* New `use_badge()` for adding any badge to a README. Now only prints a 963 todo message if the badge does not already exist. 964 965* `use_directory()` is now exported (#27). 966 967## Bug fixes and minor improvements 968 969* Functions which require code to be copied now automatically put the code on 970 the clipboard if it is available (#52). 971 972* `create_package()` no longer creates a dependency on the current version of 973 R. 974 975* `use_build_ignore()` now strips trailing `/` 976 977* `use_git()` will restart RStudio if needed (and possible) (#42). 978 979* `use_github()` now has an organisation parameter so you can create repos 980 in organisations (#4). 981 982* `use_template()` and `use_test()` now convert title to a slug that only 983 contains lowercase letters, numbers, and `-`. 984 985* `use_vignette()` now adds `*.html` and `*.R` to your `.gitgnore` so you 986 don't accidentally add in compiled vignette products (#35). 987 988* `use_travis_badge()` and `use_appveyor_badge()` are now exported functions, 989 so they can be used even if ci was separately set up (#765, @smwindecker). 990