-
Notifications
You must be signed in to change notification settings - Fork 5
/
001-tidyup-process.Rmd
135 lines (90 loc) · 7.1 KB
/
001-tidyup-process.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
---
output: github_document
---
# Tidyup 1: what is a tidyup?
**Champion**: Hadley Wickham
**Co-champion**: Tracy Teal
**Status**: Accepted
## Abstract
For bigger architectural changes, particularly those that span multiple packages or are likely to affect larger number of users, we need a process to clearly document the problem, describe possible solutions, record our decisions, and collect feedback from the community.
This document proposes the **tidyup** as a lightweight way of navigating that process.
For now, tidyups can only be proposed by the tidyverse team at RStudio, but we plan to open up the process to the wider community once we have more experience with it.
## Motivation
To date, our process for making bigger changes has been relatively informal.
This has made it easy for us to rapidly make changes but comes with some substantial downsides:
- There's no standard way to invite feedback from the community.
This means that we get useful feedback too late or not at all, and is a lost opportunity to build deeper engagement with the community.
- It's easy to lose track of solutions proposed and discarded early in the process.
This can lead to substantial repeated work if we later discover a constraint that requires us to rethink the proposed approach.
- By keeping design decisions internal, interested external developers can't see "how the sausage is made" and learn from our experiences.
## Solution
To solve this problem, I propose a lightweight framework called a tidyup.
Tidyups follow a standard process that ultimately leads to an .Rmd in <https://github.com/tidyverse/tidyups>.
The following sections describe the basic process, the sections that most tidyups should contain, and a few notes about the scope of tidyups.
The goal is to reach [rough consensus](https://datatracker.ietf.org/doc/html/rfc7282): not everyone needs to agree on every detail, but there should be a general belief that the proposal is a net positive and all major concerns should be documented, even if not resolved.
### Process
1. **Propose**.
Start by raising idea in tidyverse slack or weekly meeting.
If there's broad agreement that the scope and timing is right, proceed to the next step.
2. **Write up**.
Create an `.Rmd` (using sections defined below) and submit PR to <http://github.com/tidyverse/tidyups>.
Once you're happy with the write up, and your co-champion has has reviewed it, proceed to the next step.
3. **Discuss**.
Book a discussion in the tidyverse weekly meeting.
Assume that everyone will at least skim the tidyup beforehand, but prepare to review the proposal with a focus on any parts that need extra discussion.
Soon after the meeting, review the meeting notes and update the tidyup with needed changes and clarifications.
If the proposal needs more discussion, repeat this step.
If the proposal is ready for wider discussion, merge the PR and continue.
(Depending on the complexity of implementation, the next two steps can be completed in either order.)
4. **Implement**.
Create a reference implementation in one or more PRs to the appropriate repos.
Update the tidyup with a link to the PRs in the implementation section.
5. **Community feedback**.
Ensure that you've rendered the `.Rmd` so it's easy for others to read.
Create a new issue that invites feedback, tag community members who might be particularly helpful, and set a date when the review period will end (at least two weeks later).
Once the review period ends, update the tidyup then close the issue.
6. **Final review**.
Once both previous steps are completed, book another tidyverse meeting for final sign off.
7. **Complete.** Merge implementation PRs into affected repos then change tidyup status to "implemented".
### Sections
Each tidyup should have the following sections.
They're not compulsory, but where possible it's best to stick to the standard so it's easier to take in a new tidyup at a glance.
- **Title**.
Includes tidyup number and short, but evocative, name.
- **Metadata**
- **Champion**: each tidyup must be championed by a member of the tidyverse team.
- **Co-champion**: every tidyup needs a co-champion who will be responsible for reviewing PRs.
- **Status:** draft, design approved (internal), design approved (external), implemented, declined.
- **Abstract**.
Short description of issue and proposed solution.
Should allow the reader to determine if this is of interest to them and whether or not to keep reading.
- **Motivation**.
What are we doing now and why does it need to change?
This can be long of short depending on the "obviousness" of the problem, how much work is needed to fix it, and whether or not the solution will require breaking changes.
- **Solution(s)**.
A description of the proposed solution or solutions.
There should be enough detail to guide an implementation.
Break this up into subsections in whatever way makes sense for the proposal.
If there are multiple potential solutions to consider, each solution should get its own subsection that discusses the pros and cons.
After a solution has been picked, add a conclusion that briefly justifies why it was picked.
- **Open issues**: While proposal is in process, record open issues that require further discussion.
- **Unresolved questions**: Track unresolved questions and lingering concerns that did not get resolved in the PR, but need to be tracked for future discussion.
- **Implementation**.
Once available, provide a link to any PRs needed to implement the proposal.
- **Backwards compatibility**.
What implications does this change have for backward compatibility?
How can any negative affects be ameliorated?
- **How to teach.** If the change is likely to affect user code, include a section briefly discussing how and when to teach.
### Scope
Generally, tidyups are most appropriate for big changes in interface or implementation that are likely to affect multiple packages.
Some past cases that would have benefited from a tidyup are:
- Making the pipe lazy.
- Overhauling dplyr to use strict vctrs policies.
- Adding case weights across tidymodels packages.
In general, a tidyup is not needed if the change only affects a single package.
There are a few exceptions:
- If developing a new package that provides similar functionality to an existing package (e.g. clock, cpp11), it's useful to have a crisp explanation of why we are building something new and not extending an existing tool.
- If the initial application is limited to a single package but it is likely to expand in the future, it's worthwhile to do more upfront planning.
Two recent examples were this would've applied are testthat 3e (since the edition idea might be used elsewhere) and `dplyr::across()` (since interface affects the design of functions elsewhere).
Some topics need to be written up so we can apply them consistently across packages, but don't need to go through the full tidyup process.
These include topics like name repair, tidyverse recycling rules, ellipsis handling (including tidy dots), and our R version compatibility policy.