# Patterns and Guidelines Project Group

###### tags: `Libs MCPs`

## Summary

Move the [Patterns](https://github.com/rust-unofficial/patterns) book into the `rust-lang` organization as a complement to the [API Guidelines](https://github.com/rust-lang/api-guidelines).

Establish a _Patterns and Guidelines_ project group under the Libs team that will determine the direction and scope of the Guidelines and Patterns projects.

## Motivations

### Clear decision making

The API Guidelines are clear recommendations that library authors should try follow by-default. Whatever the Guidelines suggest should automatically set library authors up for the best chance at maintaining stable APIs over long periods. With that kind of responsibility, the Libs team as a whole should have a good idea of what's actually being recommended.

### Filling in content gaps

There are other official resources in the Rust project, like the Rustonomicon, dev guides, and standard library documentation itself that could all benefit from cross-referencing and content sharing.

### Creating space to discuss and communicate patterns

Discussion on API design and general patterns is sometimes generated out of `rust-lang/rust` contributions themselves. Having a forum to direct those discussions to will help gather interesting scenarios together that can be potentially captured as Guidelines or Patterns.

Other resources, like the `std-dev-guide` make recommendations that are specific to the standard library, but may also benefit a wider audience. Having a dedicated resource to direct those recommendations to will help the community keep in touch with best practices spawned out of the project itself.

## 2021 Charter

| Parent | Home | Handle |
| -------- | --------------- | ---------------------------- |
| Libs | `libs-team` | `@rust-lang/project-patterns-guidelines` |

### How does this group define success?

Success means:

- Relevant and useful resources to support Rust users in their own work.

This can be measured through:

- The level of discussion and cross-referencing between the API Guidelines and Patterns.
- The applicability of the API Guidelines and Patterns to large Rust codebases, like the Standard Library and `tokio`.

### What does this group do?

#### Concrete first steps

The [Patterns](https://github.com/rust-unofficial/patterns) book will be moved from its current home in `rust-unofficial` to `rust-lang/patterns`.

This may involve a few changes to fit into the Rust project, including adopting Rust's code of conduct and aligning CI with other resources.

Other early questions will need to be answered on the scope of the Patterns book, and whether it should or shouldn't recommend using external libraries and frameworks.

#### Initial goal

A concrete output of the project group will be the production of a complete 2021 edition of the API Guidelines and Patterns books.

Some patterns have changed and new idioms have emerged since we last spent time on the API Guidelines. There are some new language features like `impl Trait` and `async` / `await` that haven't been fully considered in the existing guidelines yet.

As of this writing, it's been about two years since any substantial new content was added to the API Guidelines. That's not necessarily an issue, we could consider the API Guidelines "done" for the 2018 language edition. Coming up to 2021 we should revist existing recommendations and see if any new ones have come up that make sense for the new edition.

#### Decision maker

The Patterns and Guidelines group will make decisions as a whole.

The group may want to assign somebody to lead, who will try keep the project on-track and act as a point of contact.

#### Accountable

The Patterns and Guidelines group will be accountable for the content in Patterns, and for shepherding discussion in both API Guidelines and Patterns.

#### Responsible

The Patterns and Guidelines group will be responsible for maintaining the content in the API Guidelines. The actual recommendations themselves will be decided by the Libs team.

#### Consulted

The Patterns and Guidelines group should be consulted on changes to the way official resources are presented or distributed.

#### Informed

The Patterns and Guidelines group should be informed of any new official resources that they may want to cross-reference.

The group should also be informed of changes in best practices and idioms.

### How does this group make decisions?

For decisions on what content to include in the API Guidelines and Patterns books, refer to the relevant _How content is added_ sections for each resource.

### What is expected of members?

Members are expected to participate in discussions on API Guidelines and Patterns, as well as contribute content.

### Where does this group work?

The group will work in discussions in the `rust-lang/api-guidelines` and `rust-lang/patterns` repositories.

### Who is the point of contact?

The `@rust-lang/project-patterns-guidelines` handle will be used to ping the group. There isn't necessarily an individual point of contact.

## Resources

This section outlines the resources that fall under the scope of the Patterns and Guidelines group.

### The API Guidelines

https://github.com/rust-lang/api-guidelines

#### Scope

The API Guidelines represent concrete recommendations that are broadly applicable for library authors to ensure their APIs are idiomatic, compatible, and maximally usable.

#### Ownership

The Libs team as a whole will be responsible for the recommendations made by the API Guidelines. That's basically always been the case, but it's worth making clear. The project group will be responsible for facilitating discussion, but Libs will decide the shape of the Guidelines through FCPs.

#### How content is added

The API Guidelines generate a lot of interest, because anybody building libraries in the ecosystem can use and contribute to them.

It's been a while since new content was added, but discussion on guidelines has continued in GitHub issues on the repository. GitHub issues historically don't scale to live discussion and need regular gardening to keep them useful and directed. There's a sense of debt in each open issue that isn't really the case for the API Guidelines. GitHub's issues UX simply isn't geared to surfacing a treasure-trove of design insight for users to explore.

Going forward, we should direct discussion, questions, and proposals related to guidelines to GitHub [discussions](https://github.com/rust-lang/api-guidelines/discussions) instead of [issues](https://github.com/rust-lang/api-guidelines/issues). The disussions feature in GitHub is a lot like issues, except discussions don't have an open or closed status and the UX is better suited to unbounded threaded comments. Discussions also offer a question/answer UX somewhat like Stack Overflow that we might want to look at sometime.

Most activity on the API Guidelines will be expected to take place in discussions, which will form a useful resource in their own right for anybody looking for a place to talk and read about API design in Rust. Issues will be reserved for concrete acitonable changes to the API Guidelines content that are either uncontroversial enough to accept on-the-spot or issue an FCP on. If an issue or pull request is opened that isn't the result of an existing discussion, or that a member of the Libs team doesn't feel is concrete enough to FCP for, then it should be converted into a discussion or closed. Pull requests that aren't for accepted changes to the guidelines (either through an FCP or on-the-spot approval) should be closed. Comments on issues with a proposed FCP should be limited to interacting with `rfcbot` to raise and resolve blocking concerns. Actual discussion of concerns should be done back in the relevant discussion. Issues will be a tool for coordinating concensus and surfacing accepted work, and discussions will be the place to talk about API design.

### The Patterns book

https://github.com/rust-unofficial/patterns

#### Scope

The current scope of the Patterns book is [wide](https://github.com/rust-unofficial/patterns/issues/116). It includes a combination of classical design patterns with examples of how they are implemented in idiomatic Rust, Rust-specific considerations, and assorted best practices. One of the goals of the project group will be to help figure out how to scope the Patterns book so that its content can be filled out without leaving large stubbed-out sections.

#### Ownership

The Patterns and Guidelines group will be responsible for the content in Patterns. The content in Patterns doesn't present concrete recommendations that are difficult to reverse, so it doesn't need the same kind of strict oversight that Guidelines does.

#### How content is added

The Patterns book should try align its use of discussions with the API Guidelines, but won't use FCPs for deciding what content to include. Somebody contributing to discussion in both the API Guidelines and Patterns should have a similar experience in both. A Libs FCP should be used to ratify complete sections of Patterns to make sure the Libs team is aligned with the content.

The set of topics and labels between Patterns and API Guidelines should be made consistent so the experience of moving between them is seamless. It shouldn't matter whether a user starts a discussion in Patterns or API Guidelines, it should eventually end up in the right place.

As an official project within `rust-lang`, the Patterns book should receive some expert input on traditionally tricky sections, and be able to link to active areas of discussion in other project groups (like the Unsafe Code Guidelines).