├── .gitignore ├── LICENSE.md ├── README.md ├── cli-prompts.md ├── documentation-prompts.md ├── github-actions-prompts.md ├── github-code-search-prompts.md ├── img ├── github-actions-avatar.png ├── let-me-github-search-that-for-you.png ├── let-me-google-that-for-you.png └── rest-of-the-owl.jpeg ├── internal └── marshal-participant-email-addresses.R ├── materials ├── pkg-dev-posit-conf-2024-GHA-cli.pdf ├── pkg-dev-posit-conf-2024-documentation.pdf ├── pkg-dev-posit-conf-2024-introduction.pdf └── pkg-dev-posit-conf-2024-testing.pdf ├── pkg-dev.Rproj └── testing-prompts.md /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | .Ruserdata 5 | *.html 6 | README_files/* 7 | *.key 8 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | ## creative commons 2 | 3 | # Attribution-ShareAlike 4.0 International 4 | 5 | Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. 6 | 7 | ### Using Creative Commons Public Licenses 8 | 9 | Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. 10 | 11 | * __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). 12 | 13 | * __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). 14 | 15 | ## Creative Commons Attribution-ShareAlike 4.0 International Public License 16 | 17 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 18 | 19 | ### Section 1 – Definitions. 20 | 21 | a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 22 | 23 | b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 24 | 25 | c. __BY-SA Compatible License__ means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License. 26 | 27 | d. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 28 | 29 | e. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 30 | 31 | f. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 32 | 33 | g. __License Elements__ means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike. 34 | 35 | h. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 36 | 37 | i. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 38 | 39 | j. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. 40 | 41 | k. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 42 | 43 | l. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 44 | 45 | m. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. 46 | 47 | ### Section 2 – Scope. 48 | 49 | a. ___License grant.___ 50 | 51 | 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 52 | 53 | A. reproduce and Share the Licensed Material, in whole or in part; and 54 | 55 | B. produce, reproduce, and Share Adapted Material. 56 | 57 | 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 58 | 59 | 3. __Term.__ The term of this Public License is specified in Section 6(a). 60 | 61 | 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 62 | 63 | 5. __Downstream recipients.__ 64 | 65 | A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 66 | 67 | B. __Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. 68 | 69 | C. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 70 | 71 | 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 72 | 73 | b. ___Other rights.___ 74 | 75 | 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 76 | 77 | 2. Patent and trademark rights are not licensed under this Public License. 78 | 79 | 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 80 | 81 | ### Section 3 – License Conditions. 82 | 83 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 84 | 85 | a. ___Attribution.___ 86 | 87 | 1. If You Share the Licensed Material (including in modified form), You must: 88 | 89 | A. retain the following if it is supplied by the Licensor with the Licensed Material: 90 | 91 | i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 92 | 93 | ii. a copyright notice; 94 | 95 | iii. a notice that refers to this Public License; 96 | 97 | iv. a notice that refers to the disclaimer of warranties; 98 | 99 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 100 | 101 | B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 102 | 103 | C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 104 | 105 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 106 | 107 | 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 108 | 109 | b. ___ShareAlike.___ 110 | 111 | In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. 112 | 113 | 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License. 114 | 115 | 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. 116 | 117 | 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. 118 | 119 | ### Section 4 – Sui Generis Database Rights. 120 | 121 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 122 | 123 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 124 | 125 | b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and 126 | 127 | c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 128 | 129 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 130 | 131 | ### Section 5 – Disclaimer of Warranties and Limitation of Liability. 132 | 133 | a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ 134 | 135 | b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ 136 | 137 | c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 138 | 139 | ### Section 6 – Term and Termination. 140 | 141 | a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 142 | 143 | b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 144 | 145 | 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 146 | 147 | 2. upon express reinstatement by the Licensor. 148 | 149 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 150 | 151 | c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 152 | 153 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 154 | 155 | ### Section 7 – Other Terms and Conditions. 156 | 157 | a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 158 | 159 | b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.t stated herein are separate from and independent of the terms and conditions of this Public License. 160 | 161 | ### Section 8 – Interpretation. 162 | 163 | a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 164 | 165 | b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 166 | 167 | c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 168 | 169 | d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 170 | 171 | > Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. 172 | > 173 | > Creative Commons may be contacted at creativecommons.org -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Package Development: The Rest of the Owl 2 | ================ 3 | 4 | ### posit::conf(2024) 5 | 6 | by Jenny Bryan 7 | 8 | ----- 9 | 10 | :spiral_calendar: August 12, 2024 11 | :alarm_clock: 09:00 - 17:00 12 | :hotel: Willapa meeting room 13 | :writing_hand: [pos.it/pkg_dev_24](https://pos.it/pkg_dev_24) 14 | 15 | ----- 16 | 17 | ## Schedule 18 | 19 | | Time | Topics | Slides | Prompts | 20 | | :------------ | :------------- | :------ | :------ | 21 | | 09:00 - 10:30 | Kick the tires of your setup
Core workflows
Let me GitHub search that for you | [slides](materials/pkg-dev-posit-conf-2024-introduction.pdf) | [prompts](github-code-search-prompts.md)| 22 | | 10:30 - 11:00 | *Coffee break* | | | 23 | | 11:00 - 12:30 | Testing | [slides](materials/pkg-dev-posit-conf-2024-testing.pdf) | [prompts](testing-prompts.md) | 24 | | 12:30 - 13:30 | *Lunch break* | | | 25 | | 13:30 - 15:00 | Documentation | [slides](materials/pkg-dev-posit-conf-2024-documentation.pdf) | [prompts](documentation-prompts.md) | 26 | | 15:00 - 15:30 | *Coffee break* | | | 27 | | 15:30 - 17:00 | GitHub Actions
Beautiful UI with cli
Topic by popular request? | [slides](materials/pkg-dev-posit-conf-2024-GHA-cli.pdf) | [GHA prompts](github-actions-prompts.md)
[cli prompts](cli-prompts.md) | 28 | 29 | ## Description 30 | 31 | In R, the fundamental unit of reusable and shareable code is a package, containing helpful functions, documentation, and sometimes sample data. 32 | Putting R code in a package is the best way to share our code with others or to share code across different projects. 33 | 34 | This workshop assumes you've already dipped your toe in package development, i.e. that you've managed to create a basic package and pass `R CMD check`. 35 | In terms of "How to draw an owl", you've definitely drawn some circles. 36 | But now it's time to draw the rest of the owl! 37 | 38 | ![](https://datasciencebox.org/images/design-owl.jpg) 39 | 40 | You will learn workflows and skills that are (a) very important for package development and (b) very different from writing R scripts. 41 | We will lean heavily on the tools and principles used by the tidyverse team, embodied in the devtools family of packages, including usethis, testthat, and roxygen2. 42 | 43 | This list of topics is indicative of what we will cover: 44 | 45 | - Fundamental daily workflows: `devtools::load_all()` and `check()` 46 | - Testing: the testthat package and the philosophy of writing tests as you go (vs. "later") 47 | - Documentation: function documentation, vignettes, and website 48 | - Data: internal data vs. data available to your user 49 | - GitHub Actions for automatically checking your package and building/deploying a pkgdown website 50 | - User interface: how to provide beautiful, informative messages with the cli package 51 | 52 | There will be chunks of time for you to do exercises throughout the day. 53 | We will make sure there are good options that allow all participants to engage with the material. 54 | But if you have your own package(s), you are welcome to use these times to apply what we're learning, e.g. about testing or documentation, in your personal packages. 55 | 56 | This will be an interactive 1-day workshop, and we will be using the RStudio IDE to work through the materials. 57 | 58 | ## Audience 59 | 60 | This course is for you if you: 61 | 62 | - Are very comfortable writing R scripts and functions. 63 | - Have already created a basic package, e.g., you've successfully worked through [The Whole Game chapter from R Packages](https://r-pkgs.org/whole-game.html) or have equivalent experience. You should also be able to follow the story in [The package within](https://r-pkgs.org/package-within.html) chapter. 64 | - Have concrete plans for one or more specific packages you want to create. You might have even started implementing these plans. 65 | - Are interested in using devtools/RStudio for package development. 66 | - Are at least curious about Git/GitHub. We won't have time to teach this explicitly, but you will certainly see Git/GitHub through out the day. 67 | 68 | We expect many participants will have more package development experience than the minimum described above. 69 | We typically see a real mix of backgrounds in workshops such as this. 70 | Participants at either extreme (very new or very experienced) should anticipate that they'll hear questions and discussion aimed at the other end of the experience spectrum and that's OK. 71 | 72 | ## Prework 73 | 74 | Each participant needs to bring their own laptop, with functioning wifi. 75 | You should be able to install software (R packages, really) and download files onto it. 76 | History shows that Windows laptops that are very locked-down by corporate IT can be extremely challenging in workshops. 77 | If you encounter permission problems while doing the setup below, that is a big red flag. 78 | Try to solve those problems in advance or bring a different computer. 79 | As a last resort, it is possible to work on [Posit Cloud](https://posit.cloud/). 80 | If you fear this might happen to you, go ahead and set up your Posit Cloud account in advance (it's free!). 81 | 82 | System setup: work through the [System setup](https://r-pkgs.org/setup.html) chapter. 83 | Main TODOs: 84 | 85 | * Install several R packages related to package development (devtools and friends). 86 | * Optional but recommended: do what is described for your operating system to be able to build and install R packages that contain compiled code. We will not use any C/C++ in the workshop! But anyone who is taking this workshop is likely to want this general capability in the near future. 87 | 88 | Personal devtools/usethis setup: work through the [usethis setup](https://usethis.r-lib.org/articles/usethis-setup.html) article 89 | Main TODOs: 90 | 91 | * Consider adding a snippet to your `.Rprofile` that attaches devtools in all interactive R sessions. 92 | * Consider setting some options in `.Rprofile` to customize usethis's behaviour: 93 | - `usethis.description` to pre-fill DESCRIPTION fields 94 | - `usethis.destdir` to designate a preferred home for local projects 95 | * Run `git_sitrep()` to get a situation report on your Git/GitHub setup. 96 | Use of Git/GitHub is not mandatory, but it is likely to enhance your workshop experience. 97 | 98 | In particular, configuring a GitHub personal access token will have a huge payoff, in the workshop and beyond. 99 | 100 | Here are a few small challenges that should test whether your system is ready to go: 101 | 102 | ```r 103 | library(devtools) 104 | 105 | # Git/GitHub "situation report" 106 | git_sitrep() 107 | 108 | # clones the Git repo holding the source of the usethis package 109 | # if your GitHub PAT is set up correctly, it will FORK and clone 110 | create_from_github("r-lib/usethis") 111 | 112 | # if you want to test whether you can install packages, from source, that have 113 | # compiled code, try this: 114 | install.packages("cli", type = "source") 115 | ``` 116 | 117 | ## Instructor and TAs 118 | 119 | * Jenny Bryan (instructor) is a software engineer at Posit, usually working on the tidyverse packages or its supporting ecosystem, and is a member of the R Foundation. She recently co-authored the second edition of [the R Packages book](https://r-pkgs.org/) and is the maintainer of the [devtools](https://devtools.r-lib.org/) and [usethis](https://usethis.r-lib.org/) packages (among others). 120 | * Tomasz Kalinowski (TA) is a software engineer at Posit and a member of the [mlverse](https://github.com/mlverse) team, contributing to the development of open-source machine learning software. He co-authored ["Deep Learning with R"](https://www.manning.com/books/deep-learning-with-r-second-edition) and maintains several R packages, including [reticulate](https://rstudio.github.io/reticulate/), [tensorflow](https://tensorflow.rstudio.com), and [keras3](https://keras3.posit.co). 121 | * Kevin Ushey (TA) is a software engineer at Posit and member of the RStudio IDE development team. He is the maintainer of the [renv](https://rstudio.github.io/renv/) package, and has contributed to a large number of packages in the R ecosystem. 122 | 123 | ----- 124 | 125 | ![](https://i.creativecommons.org/l/by/4.0/88x31.png) This work is 126 | licensed under a [Creative Commons Attribution 4.0 International 127 | License](https://creativecommons.org/licenses/by/4.0/). 128 | -------------------------------------------------------------------------------- /cli-prompts.md: -------------------------------------------------------------------------------- 1 | Take an existing package (your own, something you cloned today, or a package you use): 2 | 3 | * Study the existing user interface (which functions are used?). 4 | * Incrementally convert the UI-providing functions (e.g. `message()` or `stop()`) to its cli equivalent. 5 | 6 | Look at the cli documentation, especially: 7 | 8 | * cli's articles: 9 | * Help topics in the "Introduction" section here: https://cli.r-lib.org/reference/index.html 10 | 11 | Find a couple of cli functions or techniques that intrigue you and use GitHub code search to look for examples of them in the wild. 12 | -------------------------------------------------------------------------------- /documentation-prompts.md: -------------------------------------------------------------------------------- 1 | ## Bring your own package 2 | 3 | If you have your own package, you could apply some of these moves we discussed: 4 | 5 | * Add documentation, using roxygen2, if you have none. 6 | * Add a README.Rmd if you don't have a README. Remember to render to README.md. 7 | * If you have a static README.md, convert it to use README.Rmd. 8 | * Add your first vignette or article. 9 | * Beef up your examples. 10 | * Add links to your documentation: 11 | - To other functions in your package 12 | - To relevant functions in another package 13 | - To vignettes (won't truly pay off until/unless you have a pkdgdown site) 14 | - To an external URL 15 | * Use `urlchecker::url_check()` to do a health check on all URLs in your package 16 | * If any of your examples change the world: 17 | - Modify them so that does not happen. 18 | - Alternatively, make sure they always restore the original state. 19 | 20 | ## Extend the libminer package 21 | 22 | At posit::conf 2023, Andy Teucher taught an introductory package development workshop: 23 | 24 | 25 | The toy package they built is called libminer and it provides interesting summaries of the packages installed on your system. Here's the final product: 26 | 27 | 28 | Copy libminer to your computer by, e.g.: 29 | 30 | * `usethis::create_from_github("ateucher/libminer")` (recommended) 31 | * `usethis::use_course("ateucher/libminer")` (if you are not a Git/GitHub user) 32 | 33 | Run `check()` to establish that all is in working order. Play with `libminer::lib_summary()` so you get a sense of what it does. 34 | 35 | Ideas for extending libminer: 36 | 37 | * Add a mention and link to `utils::installed.packages()` to the help for `lib_summary()`. 38 | * Create a (tiny) vignette for libminer. It's OK if it basically has the same content as README. 39 | * Add another function to libminer, document it, create links from the new function to `lib_summary()` and vice versa. Add usage of the new function to `README.Rmd` and re-render `README.md`. Inspiration: 40 | - Look at the information returned by `utils::installed.packages()`. There's more interesting stuff there! Such as `Priority`, `Depends`, and `NeedsCompilation`. 41 | - For each `LibPath`, tabulate the `Priority` of the packages installed there. (Ideally the base and recommended packages live in one library and user-installed add-on packages live in another library, so this is the beginning of a "package library health check".) 42 | - For all installed packages (maybe split out by `LibPath`?), report something about the treatment of R in `Depends`. Is a minimum version of R stated at all? Tabulate the mininum R version requirements. 43 | 44 | ## Treasure hunt 45 | 46 | Use your GitHub code search skills to find and study some of the special techniques we discussed: 47 | 48 | * How prevalent is `README.Rmd`? Hint: you might need to look in `.Rbuildignore` to detect this, because only `README.md` will make it into the source package on CRAN. 49 | * Can you find folks using the `vignette("things", package = "somepkg")` in help topics? In vignettes? 50 | * Look for usage of `@examplesIf`. What sort of code do you see evaluated there, i.e. that controls whether the example should execute? 51 | * Look for packages that change the world in their examples. Do they restore the original state? You can't write a super precise search query for this, but you should be able to get somewhere. 52 | -------------------------------------------------------------------------------- /github-actions-prompts.md: -------------------------------------------------------------------------------- 1 | ## Bring your own package 2 | 3 | If you have your own package and it's on GitHub: 4 | 5 | * `use_github_action()` and choose "check-standard". This is a good idea for anyone / any package. 6 | * If you use testthat for testing, do `use_github_action()` and choose "test-coverage". 7 | * `use_pkgdown_github_pages()` will start to build and deploy a pkgdown site. 8 | 9 | ## regexcite 10 | 11 | If you don't have your own package, but you did fork and clone regexcite earlier today, you could do any of the suggestions above for your fork of regexcite. 12 | 13 | ## libminer 14 | 15 | If you don't have your own package, but you did fork and clone libminer earlier today, you can **update** its GHA workflows, which need a refresh (they were configured a year ago). 16 | 17 | First, visit the Actions tab of your fork. You'll probably see a message like this: 18 | 19 | > Workflows aren’t being run on this forked repository 20 | > 21 | > Because this repository contained workflow files when it was forked, we have disabled them from running on this fork. Make sure you understand the configured workflows and their expected usage before enabling Actions on this repository. 22 | 23 | Go ahead and click on "I understand my workflows, go ahead and enable them". 24 | 25 | Now, locally, you can overwrite the GHA YAML files, to reflect the current workflows we're using: 26 | 27 | * `use_github_action("check-standard")`. Look over the changes, commit, and push. 28 | * `use_github_action("pkgdown")`. Look over the changes, commit, and push. 29 | -------------------------------------------------------------------------------- /github-code-search-prompts.md: -------------------------------------------------------------------------------- 1 | ## A collection of prompts to practice using GitHub code search 2 | 3 | Good entry point into the documentation: 4 | https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax 5 | 6 | --- 7 | 8 | Find the R package this Mastodon post is referring to: 9 | 10 | https://fosstodon.org/@michaelchirico/112842879750705908 11 | 12 | (PackageS, plural, really.) 13 | 14 | --- 15 | 16 | The `col_type` argument to `readr::read_csv()` seems to be used in different ways? How can I see ways people are using it? 17 | 18 | What if I wanted results from `readr::read_delim()` as well? 19 | 20 | How can you filter out Python hits? Or hits in `.Rd` files? 21 | 22 | --- 23 | 24 | What packages are attached when someone does `library(tidyverse)`? 25 | 26 | Hint: it probably happens inside the `.onAttach()` function inside the tidyverse package. 27 | 28 | What other CRAN packages use `.onAttach()` and what do they do there? 29 | 30 | Where do people tend to define `.onAttach()` (as in, in which file)? 31 | 32 | --- 33 | 34 | Which tidyverse packages use cpp11 (a package that helps you incorporate C++ code)? 35 | 36 | Hint: this can be determined from the `LinkingTo` field in the `DESCRIPTION` file. 37 | 38 | --- 39 | 40 | When did `trimws()` first appear in base R? 41 | 42 | --- 43 | 44 | Where is the implementation for `is.na()` (in base R)? 45 | 46 | --- 47 | -------------------------------------------------------------------------------- /img/github-actions-avatar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/img/github-actions-avatar.png -------------------------------------------------------------------------------- /img/let-me-github-search-that-for-you.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/img/let-me-github-search-that-for-you.png -------------------------------------------------------------------------------- /img/let-me-google-that-for-you.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/img/let-me-google-that-for-you.png -------------------------------------------------------------------------------- /img/rest-of-the-owl.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/img/rest-of-the-owl.jpeg -------------------------------------------------------------------------------- /internal/marshal-participant-email-addresses.R: -------------------------------------------------------------------------------- 1 | library(readxl) 2 | library(tidyverse) 3 | library(clipr) 4 | 5 | dat <- read_excel("~/Downloads/Workshop Registrations Aug 5.xlsx") 6 | dat |> 7 | filter(`SESSION TITLE` == "Package Development: The Rest of the Owl 8 | ") |> 9 | pull(EMAIL) |> 10 | str_c(collapse = ",") |> 11 | write_clip() 12 | -------------------------------------------------------------------------------- /materials/pkg-dev-posit-conf-2024-GHA-cli.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/materials/pkg-dev-posit-conf-2024-GHA-cli.pdf -------------------------------------------------------------------------------- /materials/pkg-dev-posit-conf-2024-documentation.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/materials/pkg-dev-posit-conf-2024-documentation.pdf -------------------------------------------------------------------------------- /materials/pkg-dev-posit-conf-2024-introduction.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/materials/pkg-dev-posit-conf-2024-introduction.pdf -------------------------------------------------------------------------------- /materials/pkg-dev-posit-conf-2024-testing.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/posit-conf-2024/pkg-dev/8f76e75391cbe08e04d52ab83338b51f709610e4/materials/pkg-dev-posit-conf-2024-testing.pdf -------------------------------------------------------------------------------- /pkg-dev.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | -------------------------------------------------------------------------------- /testing-prompts.md: -------------------------------------------------------------------------------- 1 | ## Modernize testing in an existing package 2 | 3 | * Get a local copy of the stringb package. You could use `create_from_github("hadley/stringb")` (preferably) or `use_course("hadley/stringb")`, for example. 4 | * Convert to testthat 3e (this will be easy!) 5 | * Enable parallel testing (https://testthat.r-lib.org/articles/parallel.html). 6 | * Find which code isn’t covered by tests (you don’t need to do anything about it yet). 7 | * Verify that `R CMD check` passes. 8 | * Convert the existing `expect_error()` to `expect_snapshot()`. (What argument do you need to set?) 9 | * Use `expect_snapshot()` to get to 100% test coverage for stringb. (Where should the new test live?) 10 | * Our style guide now recommends that all error messages end in a full stop. Add that full stop to the messages, verify that the tests now fail, and then accept the change so that they pass again. 11 | * Verify that `R CMD check` passes. 12 | 13 | ## Align R and test files 14 | 15 | In an existing package, use the code snippet in the help for `usethis::use_r()` to figure out how well matched / unmatched the `R/*.R` and `test/testthat/test-*.R` files are. 16 | 17 | Fix that. `usethis::rename_files()` might help, depending on where you're starting from. 18 | 19 | ## Setup keyboard shortcuts for common testing "moves" 20 | 21 | Here's a good resource on customizing RStudio keyboard shortcuts: 22 | https://docs.posit.co/ide/user/ide/guide/productivity/custom-shortcuts.html 23 | 24 | devtools addins that are nice to have keybindings for: 25 | 26 | * `devtools::test_active_file()`: consider Cmd/Ctrl + T 27 | * `devtools::test_coverage_active_file()`: consider Cmd/Ctrl + R 28 | 29 | ## Learn if tests are leaking state 30 | 31 | Use `testthat::set_state_inspector()` on an existing package to see if some of its tests are _not_ leaving the world the way they found it. 32 | 33 | Ideas for what to look for: 34 | 35 | * Files left behind in the temp directory. 36 | * Modified R options. 37 | * Modified environment variables. 38 | 39 | Search for `set_state_inspector()` if you want to see organic usage and get more ideas of which aspects of state people check for. 40 | 41 | ## Look for `library()` and `source()` calls in a test suite 42 | 43 | Use GitHub code search to look for CRAN packages that call `library()` or `source()` inside their testthat test suite. 44 | 45 | Grab a local copy of such a package and see if you can refactor it to use more official testthat methods to achieve whatever it is they're trying to do. 46 | 47 | *You could conceivably make a pull request to such a package, but it's risky to offer this sort of unsolicited feedback. Proceed with caution.* 48 | 49 | ## Look for test helpers 50 | 51 | Search packages on CRAN or in, e.g., the tidyverse or r-lib organization for test helpers. 52 | 53 | Single-most likely file for these is `tests/testthat/helper.R`. 54 | 55 | But they could also be in a file like `tests/testthat/helper-foo.R`. Or even defined in `R/` (although those might be hard to find just based on file name). 56 | 57 | Once you've found some test helpers, study them: 58 | 59 | * What sort of functionality do the test helpers offer? 60 | * How are they used inside that package's tests? 61 | 62 | Do the same but for test setup files, e.g., `tests/testthat/setup.R`. 63 | 64 | ## Look for test fixtures 65 | 66 | The function `test_path()` is a helpful and robust way to build a path to a file inside a package's test directory. 67 | 68 | Search for uses of `test_path()` and see what it's being used for. 69 | --------------------------------------------------------------------------------