Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update introduction.Rmd #1017

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions introduction.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ If you're reading this book, you already know how to work with packages in the f
The goal of this book is to teach you how to develop packages so that you can write your own, not just use other people's.
Why write a package?
One compelling reason is that you have code that you want to share with others.
Bundling your code into a package makes it easy for other people to use it, because like you, they already know how to use packages.
Bundling your code into a package makes it easy for other people to use it because, like you, they already know how to use packages.
If your code is in a package, any R user can easily download it, install it and learn how to use it.

But packages are useful even if you never share your code.
Expand All @@ -51,15 +51,15 @@ The usethis package is the sub-package you are most likely to interact with dire

As always, the goal of devtools is to make package development as painless as possible.
It encapsulates the best practices developed by Hadley Wickham, initially from his years as a prolific solo developer.
More recently, he has assembled a team of developers at Posit (formerly known as RStudio), who collectively look after hundreds of open source R packages, including those known as [the tidyverse](https://www.tidyverse.org).
More recently, he has assembled a team of developers at Posit (formerly known as RStudio), who collectively look after hundreds of open-source R packages, including those known as [the tidyverse](https://www.tidyverse.org).
The reach of this team allows us to explore the space of all possible mistakes at an extraordinary scale.
Fortunately, it also affords us the opportunity to reflect on both the successes and failures, in the company of expert and sympathetic colleagues.
We try to develop practices that make life more enjoyable for both the maintainer and users of a package.
The devtools meta-package is where these lessons are made concrete.

devtools works hand-in-hand with RStudio, which we believe is the best development environment for most R users.
The most popular alternative to RStudio is currently [Visual Studio Code](https://code.visualstudio.com/) (VS Code) with the [R extension](https://marketplace.visualstudio.com/items?itemName=REditorSupport.r) enabled.
This can be a rewarding and powerful environment, however it does require a bit more work to set up and customize[^introduction-1].
This can be a rewarding and powerful environment; however, it does require a bit more work to set up and customize[^introduction-1].

[^introduction-1]: Users of [Emacs Speaks Statistics](https://ess.r-project.org/) (ESS) will find that many of the workflows described in this book are also available there.
For those loyal to vim, we recommend the [Nvim-R plugin](https://github.com/jalvesaq/Nvim-R).
Expand All @@ -83,17 +83,17 @@ Writing R extensions is a useful resource once you've mastered the basics and wa

The first part of the book is all about giving you all the tools you need to start your package development journey and we highly recommend that you read it in order.
We begin in @sec-whole-game with a run through the complete development of a small package.
It's meant to paint the big picture and suggest a workflow, before we descend into the detailed treatment of the key components of an R package.
It's meant to paint the big picture and suggest a workflow before we descend into the detailed treatment of the key components of an R package.
Then in @sec-setup you'll learn how to prepare your system for package development, and in @sec-package-structure-state you'll learn the basic structure of a package and how that varies across different states.
Next, in @sec-workflow101, we'll cover the core workflows that come up repeatedly for package developers.
The first part of the book ends with another case study (@sec-package-within), this time focusing on how you might convert a script to a package and discussing the challenges you'll face along the way.

The remainder of the book is designed to be read as needed.
Pick and choose between the chapters as the various topics come up in your development process.

First we cover key package components: @sec-r discusses where your code lives and how to organize it, @sec-data shows you how to include data in your package, and @sec-misc covers a few less important files and directories that need to be discussed somewhere.
First, we cover key package components: @sec-r discusses where your code lives and how to organize it, @sec-data shows you how to include data in your package, and @sec-misc covers a few less important files and directories that need to be discussed somewhere.

Next we'll dive into to the package metadata, starting with `DESCRIPTION` in @sec-description.
Next, we'll dive into to the package metadata, starting with `DESCRIPTION` in @sec-description.
We'll then go deep into dependencies.
In @sec-dependencies-mindset-background, we'll cover the costs and benefits of taking on dependencies and provide some technical background on package namespaces and the search path.
In @sec-dependencies-in-practice, we focus on practical matters, such as how to use different types of dependencies in different parts of your package.
Expand Down