004-governance.md

Tidyup 4: governance model

Champion: Hadley Wickham
Co-champion: Tracy Teal
Status: Accepted

Abstract

Our open source packages currently lack a well defined governance model. We do have a basic set of assumptions under which we operate, but we have not previously made them precise. This tidyup lays out a model that strikes a balance between the benevolent dictator and rough consensus models, and defines the relationships between four key roles: a large community of users, a smaller pool of GitHub contributors, a team of authors, and one maintainer.

Motivation

One package (ggplot2) currently has a formal governance model, while all others use an informal, undocumented model. The goal of this tidyup is to come up with a flexible model that can become our default governance model going forward. This is part of a general movement to get better at defining and documenting our processes so that there’s a clear path from package user to package developer and outline how decisions are made.

Solution

The following sections describe a governance model to use as a default for open source RStudio repositories (starting with those in the tidyverse organisation and expanding to r-lib and tidymodels in the near future). It is not mandatory, but it has been designed to reflect our current best practices, and should be used unless there are compelling reasons to favour a different approach.

The model strikes a balance between the benevolent dictator and rough consensus governance models. We blend these two governance models because we want to involve the community in decision making as much as possible, while recognising that excellent user experience often requires consistent design guided by a single voice.

The following sections define the four key roles (users, contributors, authors, and maintainers) and a couple of common processes.

Roles

Users

People who use the package are the most important members of the community; without these users, this project would have no purpose. Users are encouraged to participate in the life of the project and the community as much as possible. Common user activities include (but are not limited to):

• Evangelising about the project.
• Asking and answering questions on community forums.
• Providing moral support (a “thank you” goes a long way).

There is no formal relationship between the project and the users, but we include them here as they’re the largest group and are the pool from which contributors are typically drawn.

Contributors

Users who continue to engage with the project and its community will often find themselves becoming more and more involved. Such users may then go on to become contributors by interacting with the project on GitHub. Contributors:

• Report bugs and suggest improvements by creating new issues.
• Improve existing issues by answering questions, creating reprexes, or providing feedback on proposed changes.
• Contribute code or documentation via pull requests.

Anyone can become a contributor: there is no expectation of commitment to the project, no required set of skills, and no selection process. The only requirements are to follow the code of conduct and contributing guidelines. Our code review principles provide advice on best practices for contributing to our packages.

Packages don’t maintain an explicit list of contributors but acknowledge them in blog posts, using data from GitHub aggregated by usethis::use_tidy_thanks(). Contributors who implement user facing changes are also acknowledged in NEWS.md.

Authors

Contributors who have made significant and sustained contributions can be invited to become authors. Authors are collectively responsible for the development of the package, including responding to issues, writing code, and reviewing pull requests.

An author possesses three special powers. They:

• Have write access on GitHub so they can label issues, close issues, request PR reviews, and merge PRs.

• Are listed in Authors@R so they are listed on the package website and included in the package citation.

• Are a member of the “authors” team of the tidyverse organisation, so they are publicly acknowledged and can easily be cc’d in tidyverse-wide discussions.

Authors are expected to follow our standard processes, such as:

• Welcoming and inclusive: Kindness and gratitude are core values of the tidyverse and we strive to create an inclusive atmosphere in our GitHub interactions. As an author, you’ll be listed as a “member” of the tidyverse across all repos, so also please bear in mind your special status in other repos.

• Code contribution: code is usually contributed via PR, even for authors who could push directly.

• Communication: authors are involved in most of the interactions with contributors and thus need to set a welcoming and inclusive tone for the project.

• PR review: all pull requests should be reviewed by at least one other author. In general, there is no expectation that PRs contain clean commit histories, but it’s appreciated where possible. Once a reviewer has marked a PR as approved, the original author finishes any remaining tasks and then merges it.

• Backward compatibility: any backward incompatible changes (i.e. changes that cause reverse dependencies to fail R CMD check or are likely to cause problems in user code) must be approved by the maintainer. Significant backward incompatible changes need to be accompanied with a plan for how they will be communicated to the community.

• CRAN releases: package releases are made on an as-needed basis, and increment either the major, minor, or patch version depending on the scope of the release. The process itself is defined by usethis::use_release_issue().

• Decision making: when a package has multiple authors, where possible, decisions are made using rough consensus amongst the authors. If consensus is hard to reach or taking too long, the maintainer will make a decision.

(We expect to flesh these processes out in the coming months.)

Authors are recruited from contributors. An invitation to join the authors can be extended to anyone who has made significant and sustained contributions, and has acted in accordance with the code of conduct.

Maintainer

A maintainer is the author with primary responsibility for the package. As well as the responsibilities of an author, they also:

• Set and clearly communicates the strategic objectives of the package.
• Oversee CRAN releases.
• On-board new authors.
• Have the final say on important decisions.
• De-escalate conflict amongst authors and/or users.
• Enforce the code of conduct.
• Recruit their replacement when they want to retire from the project.

A maintainer has two special powers:

• They have admin access on Github, allowing them to add new authors when needed.

• In their Authors@R listing they have an email address and the “cre” role. “cre” is short for creator and while a maintainer often isn’t the creator, CRAN mandates the use of this role.

The maintainers of most of RStudio’s open source repositories are RStudio employees. This is not a requirement but a recognition of the tension between making development open to all and ensuring that users can trust that a package will be maintained in the long term (i.e. 10+ years), which typically requires the maintainer be explicitly remunerated for their work. Where the maintainer is not an employee of RStudio, we ask for the “right of first refusal” — if the maintainer wants to stop maintaining the package (for whatever reason) they first offer it back to RStudio. In the future, we hope to find other ways of financial supporting maintainers apart from full-time employment.

Process

Invite author

To on-board a new author, the maintainer looks for rough consensus amongst authors by emailing them (since this needs to be done privately). In this case, one signal of rough consensus would be no objections within 7 days.

The maintainer then sends the following email to the proposed author:

Hi {name},

In recognition of your significant contributions to {package}, would you be interested in becoming a package author? You can read about the rights and responsibilities of a package author at https://github.com/tidyverse/tidyups/blob/main/004-governance.md#authors, but in short, being an author means that you’ll be acknowledged in Authors@R, given write permission on GitHub, and added to the tidyverse authors GitHub team. You’ll continue to use PRs to contribute code, but merge your own PRs once they’ve been reviewed, and you can now review PRs from others.

If you accept please respond to this email then prepare a PR that:

• Adds your info to Authors@R.
• Tweaks _pkgdown.yml if you want to link your name to your website on the package website.
• Advertises the change in NEWS.md.
• Re-builds the documentation to get updated package docs.

I’ll then give you write access and approve the PR, then you can squash-merge it, which will be our PR workflow going forward. (You’ll also be able to request reviews from me and other authors as needed.)

Thanks for all your work on {package}!

{your_name}

Once the author responds:

• Add them as member of the GitHub tidyverse authors team.

• Give them write access to the specific repository.

• If this is the first non-RStudio author, strongly consider protecting the main branch and requiring one review. This helps newer authors feel confident there’s no way for them to accidentally mess up the repo.

• Send a celebration tweet.

Change maintainer

We do not yet have a process for selecting a new maintainer when the existing maintainer retires, but the following mechanical things need to happen:

• Give new maintainer admin access.

• Remove admin access from old maintainer.

• Remove “cre” role and email address from old maintainer, and add role and email address for new maintainer.

• Submit patch release to CRAN to confirm maintainer change.

• Add bullet to NEWS.

Open issues

• Do we need a brief write up of the tidyverse teams?

• What steps do we need to take to align existing repos with the new policy? Does this replace the ggplot2 governance model?

• How do we share with the community, new authors etc?

Lingering concerns

• Use of team discussions is a new communication mechanisms. Is this going to cause problems?

• We are not currently considering a more open model where as soon as you get your first PR merged you’re given write access (e.g. trio). Should we be?