devtools 2.0.0

  devtools, r-lib

  Jim Hester

Introduction

devtools 2.0.0 is now on CRAN!

devtools makes package development easier by providing R functions that simplify and expedite common tasks. R Packages is a book based around this workflow.

devtools 2.0.0 is a major release! It contains all work from the last major release (1.13.0) more than a year and a half ago!

Breaking changes

There are a handful of breaking changes in this release, mainly done in the interest of simplifying and standardizing the function APIs.

The changes should affect relatively little user code, but have required developers to make changes. Common errors and ways to work around them as well as the full list of changes can be found in the Breaking changes section of devtools’ NEWS. If you discover something missing, please let us know so we can add it.

Conscious uncoupling

This release splits the functionality in devtools into a number of smaller packages which are simpler to develop and also easier for other packages to depend on. In particular the following packages have been spun off in what we are calling the conscious uncoupling of devtools.

  • remotes: Installs packages (e.g. install_github()).
  • pkgbuild: Builds binary packages (including checking if build tools are available) (e.g. build()).
  • pkgload: Simulates package loading (e.g. load_all()).
  • rcmdcheck: Runs R CMD check and reports the results (e.g. check()).
  • revdepcheck: Runs R CMD check on all reverse dependencies, and figures out what has changed since the last CRAN release (e.g. revdep_check()).
  • sessioninfo: R session info (e.g. session_info()).
  • usethis: Automates package setup (e.g. use_test()).

devtools will remain the primary package developers will interact with when writing R packages; it will just rely on these other packages internally for most of the functionality.

Generally, you should not need to worry about these different packages, because devtools installs them all automatically. You will need to care, however, if you’re filing a bug because reporting it at the correct place will lead to a speedier resolution.

Package developers who wish to depend on devtools features should also pay attention to which package the functionality is coming from and depend on that rather than devtools. In most cases packages should not depend on devtools directly. This is similar to the situation with the tidyverse package.

New features

The majority of the work for this release was related to bugfixes and infrastructure improvements, but there are also some new features you may notice.

As always a complete list of all the changes is available in the package Changelog.

Upgrade menu

All of the install functions (e.g. install_github()) now prompt the user with a menu if there are dependencies of the package being installed which are outdated. This allows the user to pick which if any they would like to upgrade.

Previous versions of devtools always upgraded these packages automatically by default, which sometimes was frustrating when you simply wanted to install one package.

When used non-interactively the install functions work like the previous default of always upgrading outdated packages.

upgrade menu

The menu respects the menu.graphics option, so set options(menu.graphics = FALSE) in your .Rprofile if you prefer text based menus, or TRUE if you prefer graphical widgets.

Improved check output

check() now uses the rcmdcheck package, which has much richer, more colorful output to the check results, making check failures much easier to see.

rcmdcheck output

Testing single files

devtools now includes functions (test_file() and test_coverage_file()) to improve development of a single file. Rather than running all tests, or manually supplying a filter argument to restrict the tests test_file() automatically runs the corresponding tests for a given source file. These functions make the feedback loop when developing new features quicker as you only run the relevant tests for the file you are editing.

This requires you use a standard naming convention for your tests, e.g. if you have a source file R/featureA.R the corresponding test file would be tests/testthat/test-featureR.R.

The tests file to run is automatically detected from the open file in RStudio (if available), so you can call test_file() with either the source file or the test file open. A corresponding test_coverage_file() function shows the test code coverage for a single source file.

There is also a test_coverage() function to report test coverage for your whole package.

These functions have RStudio addins which allows you to bind them to shortcut keys.

Shortcuts we recommend

Function Windows shortcut macOS shortcut
test_file() Ctrl+T Command ⌘ +T
test_coverage_file() Ctrl+R Command ⌘ +R
test_coverage() Ctrl+Shift ⇧+R Command ⌘ +Shift ⇧+R

Spell checking

spell_check() can be used to check the spelling of package documentation using the spelling package. We have found checking spelling before a release often catches a number of errors. For more details on features of the spelling package see the rOpenSci spelling release post.

Also see usethis::use_spell_check() to have spell checking for the package performed automatically during devtools::check().

Acknowledgements

This release was truly a team effort! Much of the work in the uncoupled packages, particularly the remotes, rcmdcheck, revdepcheck and sessioninfo packages was done by Gábor Csárdi. Hadley Wickham worked extensively on pkgbuild, pkgload and usethis (as well as being responsible for most of the original code in devtools) and Jenny Bryan had major contributions to the usethis package.

The work spanned over 8 packages (devtools + the uncoupled packages) and includes 1,579 commits, 1,487 closed issues and 107 different code contributors!

We are of course grateful to all of the 336 people who contributed not just code, but also issues and comments for this release: @ankane, @ashiklom, @bleutner, @coatless, @dandelo, @dleutnant, @dpprdan, @evanbiederstedt, @gaborcsardi, @glin, @gungne, @hadley, @heavywatal, @imanuelcostigan, @jennybc, @jimhester, @jogrue, @jonasfoe, @joshuaulrich, @jsal13, @KasperSkytte, @krlmlr, @LiNk-NY, @lorenzwalthert, @nbenn, @overmar, @paulobrecht, @pgensler, @profandyfield, @r-cheologist, @rcannood, @richfitz, @robertdj, @rtobar, @surmann, @trinker, @VincentGuyader, @vsabarly, @vspinu, @wch, @wibeasley, @yutannihilation, @aravind-j, @eddelbuettel, @helix123, @HughParsonage, @jrosen48, @noamross, @pat-s, @wlandau-lilly, @baptiste, @bbolker, @benjaminhlina, @colearendt, @HenrikBengtsson, @IndrajeetPatil, @jeroen, @kevinushey, @lionel-, @nitisethi28, @schloerke, @topepo, @lcolladotor, @llrs, @patperry, @bgoodri, @dpastoor, @karldw, @kylebmetrum, @njtierney, @richierocks, @sangeetabhatia03, @theGreatWhiteShark, @benmarwick, @billdenney, @Dripdrop12, @friendly, @isteves, @mb706, @pitakakariki, @prosoitos, @tetron, @yiufung, @adomingues, @alexholcombe, @alexpghayes, @andrie, @atheriel, @batpigandme, @behrman, @bestdan, @bfgray3, @bhaskarvk, @boshek, @cboettig, @cderv, @chris-billingham, @Chris-Engelhardt, @chris-prener, @CorradoLanera, @dchiu911, @dirkschumacher, @dougmet, @dragosmg, @duckmayr, @echasnovski, @eheinzen, @EmilHvitfeldt, @GregorDeCillia, @gvegayon, @gvelasq, @hafen, @HanjoStudy, @ijlyttle, @jackwasey, @jasonserviss, @jayhesselberth, @jdblischak, @jjchern, @jmgirard, @jonocarroll, @jsta, @karawoo, @katrinleinweber, @kiwiroy, @lbusett, @lwjohnst86, @maelle, @maislind, @malcolmbarrett, @markdly, @martinjhnhadley, @maurolepore, @mdlincoln, @mine-cetinkaya-rundel, @mixtrak, @muschellij2, @nijibabulu, @PeteHaitch, @rdrivers, @romainfrancois, @rorynolan, @s-fleck, @seankross, @strboul, @tjmahr, @uribo, @vnijs, @webbedfeet, @1beb, @ackleymi, @akubisch, @alexilliamson, @alistaire47, @amilenkovic, @amstilp, @AmundsenJunior, @AndreMikulec, @andrewrech, @andriuking, @anhqle, @Ashilex, @Bandytwin, @bastistician, @BenoitLondon, @bgctw, @BillPetti, @bioinformatist, @bioticinteractions, @Bustami, @carlganz, @cbail, @cdeterman, @cfhammill, @chiarapiccino, @ChrisMuir, @ck37, @cklunch, @courtiol, @crossxwill, @daattali, @damianooldoni, @darsoo, @dataisdata, @DavisVaughan, @dbaston, @deephoot, @dfrankow, @DiogoFerrari, @DivadNojnarg, @djm158, @djvanderlaan, @dmenne, @dmurdoch, @DocOfi, @dracodoc, @dtelad11, @EmilBode, @epurdom, @Fazendaaa, @feng-li, @FilipeamTeixeira, @flying-sheep, @fmichonneau, @gbouzill, @GeoBosh, @gilbertocamara, @Gioparra91, @gitter-badger, @goranbrostrom, @guhjy, @gwarnes-mdsol, @gzagatti, @ha0ye, @holgerbrandl, @Hong-Revo, @hrbrmstr, @hughjonesd, @ianmcook, @Isaacsh, @Jadamso, @james-atkins, @JamesSteeleII, @jceleste1991, @jefshe, @jiaqitony, @JiaxiangBU, @jkraut, @joeddav, @JohnMount, @joncfoo, @jonkeane, @josherrickson, @JustinMShea, @KallyopeBio, @kanasethu, @karlropkins, @Keaton1188, @kemin711, @kenahoo, @kendonB, @kimyen, @klmr, @kmcconeghy, @komalsrathi, @krshedd, @layik, @lindbrook, @lucacerone, @magic-lantern, @malwinare, @MansMeg, @MarcHiggins, @MarkEdmondson1234, @martin11112, @mattfidler, @mdavy86, @meowcat, @mhines-usgs, @MichaelM27, @michaelwhammer, @mikemeredith, @mikldk, @MilesMcBain, @mjpnijmeijer, @mkearney, @mkhezr, @mojaveazure, @moodymudskipper, @MrFlick, @mroemer, @mrustl, @ms609, @msberends, @mtmorgan, @mvuorre, @myaseen208, @navdeep-G, @neekro, @Neil-Schneider, @ngreifer, @nick-youngblut, @nmattia, @ntdef, @okayaa, @paternogbc, @paul-buerkner, @paulmartins, @pavel-filatov, @Paxanator, @peterhurford, @petermeissner, @pfgherardini, @plantarum, @potterzot, @privefl, @qpcg, @renkun-ken, @renozao, @rpruim, @RS-eco, @RSIGitHubAdmin, @sammo3182, @SanVerhavert, @saurfang, @sfirke, @ShanSabri, @skhiggins, @SrinivasTammana, @StanleyXu, @statquant, @stla, @stumoodie, @sushilashenoy, @Swarje, @SymbolixAU, @talgalili, @tbates, @tfitzhughilx, @thk686, @ThorleyJack, @TinkaMiau, @TKoscik, @tungmilan, @twolodzko, @unDocUMeantIt, @vaibhav2903, @vermouthmjl, @vishnu1994, @wehc1, @wldnjs, @wolski, @xingbaodong, @Xinzhu-Fang, @YanpingGuo312, and @yurivict