# Lang team "shepherded project" proposal

## Key ingredients

A **shepherded project** has the following "key ingredients":

* Assigned **shepherd(s)** (and lang team **liason**, maybe same person)
* Create a **repository** which contains at least the following:
* charter, defining scope and goals of the project
* exploration report, survey alternatives
* current design, going into detail
* design reports, documenting the reasons behind tricky or key decisions

## Officers

"Officers" are members of the group who play a special role. They are often among the founding members of the group, though the set of active officers can also change over time.

When first created, a project must define one or more shepherds along with a lang team liason:

* **Shepherds** have the job of guiding the overall design and conversation:
* They can be a lang-team member but do not have to be.
* They also make regular updates to the lang team.
* The first goal in any design conflict should be to fully and accurately describe the conflict and to identify the "key tradeoffs" being made.
* If none of them shepherds is a lang-team member, then there should be a **liason** as well.
* The liason is somebody who the shepherds can come to with questions and so forth.

Groups may define additional officers as needed. For example, it is useful to have a **reviewer** and an **implementor** (who is writing the code). Similarly, it would be useful to recognize the people who are writing documentation. As we gain more experience, we'll probably come up with a "standard set" of such officers that groups tend to have.

### Decision makers

In general, project groups don't "make the final decisions" -- the Rust teams do (e.g., lang team, compiler team, etc). However, in practice, a lot of the smaller details *do* wind up getting decided by the project group, with the lang team opting to trust their judgement. Therefore, it can be useful to define the formal decision makers for the group itself.

By default, this set is just the shepherds and lang team liason, and that suffices for most projects. In some cases though it might be useful to have a larger set of folks.

### General membership

It is not yet clear whether it makes sense to formally define other members beyond the officers. If nothing else, it can be a good way to recognize people who have contributed in a significant way to the design and discussion of a project. In that case, it is recommended that membership be granted to folks who have been contributing for some time in a consistent way.

## Stages of a project

The **stages** of a project are determined by which of the documents they have that have been **approved** by the lang team. There are four major phases:

1. **Drafting charter** -- figuring out the rough goals/non-goals
2. **Exploring the solution space** -- figuring out what the options are and picking the best
3. **Developing the solution** -- building a test suite and developing the feature itself; also requires writing an explainer to help people use it
4. **Stabilizing and documenting** -- the feature becomes available on stable and we work on updating the reference or other "main bits" of documentation as appropriate

Projects typically begin in the first phase. But in some cases we can just right to the 2nd or 3rd phase if the problem seems sufficiently simple.

### Stage 0: Sponsored

- To start, create a lang team proposal, and a liaison takes interest in this
- Lightweight decision making process:
- someone has to

#### Exit criteria

- There must be a lang-team liaison assigned, who has available bandwidth.
- There must be lang-team consensus that the problem *should* be solved, somehow, and should be part of Rust.

### Stage 1: Drafting a charter

- When first created, projects typically have a shepherd, liason, and a draft charter. They begin then by fleshing out the charter and identifying non-goals.
- In this time they can also begin creating the exploration report, as often this discussion will lead to a certain amount of exploration.

#### Exit criteria

- Present the fully fleshed out charter to the lang team for approval.
- Criteria should identify goals and non-goals.
- Reasons to **accept**: you think this problem is sufficiently important and that there is sufficient bandwidth available to see it through. For implementation heavy projects, this may require checking in with other teams, especially the compiler team.
- Reasons to **block**: you do not think the charter has a clear or completable scope; you do not think there is available bandwidth or you do not feel that this problem is worth solving, compared to the other problems on hand.

### Stage 2: Exploring the solution space

- In this phase projects are exploring the solution space more deeply. The goal is to enumerate the possible solutions and ultimately select one solution as the preferred direction.
- Entering this stage implies that the **lang team agrees they would like to solve this problem in principle**.
- In this stage, the lang team agrees that implementation work can begin in tree, though the goal should be to "prove out" possible solutions and not to develop the full feature. If at all possible, such work should be done in procedural macros or otherwise "out of tree".
- NB. Landing PRs *in tree* also requires agreement with the compiler team. See the discussion below.
- The result of this stage can be either:
- continue work by moving to the "developing the solution" stage
- put the work on hold

#### Exit criteria when moving to development

- Present the recommended solution and explain why the other solutions were not preferred
- The recommended solution should come with a set of examples that will be the seed of the final test suite.
- This test suite should show how the goals of the charter are met (or not met, as may be the case; in which case those goals will become non-goals).
- It should also include a list of "unresolved questions" that are expected to be worked out over the remainder.
- In general, lang team members should prefer to add things to the list of unresolved questions rather than blocking the proposal from moving forward.
- Reasons to **accept**:
- the proposed solution seems like the best approach
- the set of examples covers all the major goals
- it is *not* required for examples to be a full test suite, that would typically be done in the next stage
- you can't think of any major alternatives worth discussing
- you think there is available bandwidth to do the remaining implementation work
- Reasons to **block**: (be specific)
- you think the proposed solution has fundamental flaws that cannot be rectified (which and in what way?).
- there is a solution you think is better (which and in what way?).
- there is a solution that doesn't seem sufficiently explored (which and in what way?).
- there are use cases that this solution does not address and without those you don't feel the work is worth doing (which and in what way?).

#### Exit criteria when moving to postpone

- **Exit criteria when moving to close or postpone:** It may be that no satisfactory solution is found. It may also be that the time doesn't seem to ripe to pursue the proposed solution (perhaps it is blocked on implementation work or another feature). In that case, the project can decide to **postpone** further work.
- Reasons to **accept**
- Not enough bandwidth to pursue now (no reviewer could be found, for example)
- Blocking on some technical detail
- Reasons to **block** (be specific)
- Well, you can't really *block* this, but if you think the problem is imporant, you might recommend ways to reduce scope and still make progress, or look to find people to help and provide more bandwidth.

### Stage 3: Developing the solution

- In this stage development work begins in earnest:
- should be developing a full test suite
- exploring the unresolved questions and coming up with proposed answers
- if appropriate, writing an explainer to help "end users" evaluate the feature
- If you reach a steady state, a good idea is to do a "call for feedback", where you point people at the explainer and encourage them to give feedback.
- Best if you can collect that feedback in a google form

#### Exit criteria

- All unresolved questions are resolved -- though the "resolution" can be an explanation of why the question can be deferred
- Complete test suite showing interaction with other language features
- Suitable explainer is available
- If appropriate, feedback from users has been received and taken into account
- **Reasons to accept:**
- You think this feature is ready to stabilize.
- **Reasons to block:** (be specific)
- You are concerned about the soundness of the feature.
- You think the test suite is missing important coverage
- You think the

### Stage 3: Stabilize and document

At this point, the feature is basically done. What is needed is to stabilize it on master and to update the reference or other such documentation.

## Charter

The purpose of the **charter** is to define the scope of the project. A good charter will clearly define the **goals** of the project, which generally take the form of a list of problems to be solved, with concrete examples. It can also define **non-goals**: things that are ruled out of scope.

The charter is not immutable and is expected to evolve over time, though its "spirit" should remain the same. It is however expected that (a) new goals and examples will arise; (b) new non-goals will be identified; and (c) previous goals may move to non-goals as the nature of the solution space becomes clear.

The charter is in some sense similar to the "motivation" section of today's RFC template, although it is likely quite a bit more general.

## Exploration report

The **exploration report** (which may actually be many files) documents the various approaches that were considered. It should explain why this particular approach was chosen. This is roughly the "alternatives" section of today's RFC template.

## Current design

The **design** documents the current approach. Like today's RFC template, it should include both the "guide-level expanation" and "reference-level explanation" of the design. Note that the "current design" can be split into multiple files as needed.

## Design reports

Design reports are created during the process when a tricky question is encountered. They document the problem, the various options that were considered, and the reasons behind the ultimate decision that was taken.

In the case of particularly contentious decisions, decision reports might also include a "dissent" from members who disagreed with the decision but chose not to block consensus (the dissent would explain their concerns). An example of where a dissent might've been appropriate is the choice to use `foo.await` syntax. The write-ups that came out of that discussion are also a good example of decision reports in action.

Decision reports are particularly useful to avoid repeated discussion. When someone raises a topic that was previously decided, you can quickly refer them to the decision report and close the discussion (unless of course there is appetite to revisit the topic).