Revamp Contributing and add GH templates #519
Conversation
leebyron
added
✏️ Editorial
This is a top-to-bottom revamp of the Contributing.md document which includes a more thorough and implementable process for identifying what stage a PR is in and what is expected to reach the next stage. It also captures the guiding principles for spec improvements.
leebyron
added
🐝 Process
There was a problem hiding this comment.
This is a clear step-change improvement over the previous documentation. Some of the stages' introductory paragraphs scanned a bit strangely to me, so I tried to deconstruct them and chop them back together, but I'd be happy shipping what's in this commit as-is.
CONTRIBUTING.md
Outdated
|
|
||
| An RFC at the *accepted* stage is a completed solution which is ready to be | ||
| merged as-is into the spec according to a spec editor and is ready to be | ||
| deployed in GraphQL libraries. |
There was a problem hiding this comment.
Thesis: Completed
Requirements: Already implemented with editor approval
Why: So compliant libraries implement it and people can use it.
An RFC at the *accepted* stage is a completed solution. According to a spec
editor it is ready to be merged as-is into the spec. The RFC is ready to be
deployed in GraphQL libraries. An *accepted* RFC must be implemented
in GraphQL.js.
CONTRIBUTING.md
Outdated
| An RFC at the *draft* stage is a fully formed solution which has working group | ||
| consensus that it is a problem worth solving and the solution is preferred. | ||
| A *draft's* goal is to precisely and completely describe the solution and | ||
| resolve any implementation concerns. A *draft* must be a pull request. |
There was a problem hiding this comment.
Thesis: fully formed solution.
Requirements: working group "worth trying to solve" consensus along with pull request.
Why: Goal is to precisely and completely describe the solution. Given a draft, different people must be able to implement identical behavior across GraphQL libraries.
An RFC at the *draft* stage is a fully formed solution. There is working
group consensus that the problem identified is worth solving, and this
particular solution is preferred. A *draft's* goal is to precisely and
completely describe the solution and resolve any concerns through library
implementations. A *draft* must be a pull request.
CONTRIBUTING.md
Outdated
| An RFC at the *proposal* stage is a solution to a problem with enough fidelity | ||
| to be discussed in detail, backed by a willing *champion*. A *proposal*'s goal | ||
| is to make a compelling case for acceptance by describing both the problem and | ||
| the solution via examples and spec edits. A *proposal* should be a pull request. |
There was a problem hiding this comment.
Thesis: discussion stage
Requirements: can be discussed in detail, backed by a champion
Why: to make a case for both the problem and potential solutions. It should foster discussion about alternatives.
An RFC at the *proposal* stage is a solution to a problem with enough fidelity
to be discussed in detail. It must be backed by a willing *champion*.
A *proposal*'s goal is to make a compelling case for acceptance by describing
both the problem and the solution via examples and spec edits. A *proposal*
should be a pull request.
CONTRIBUTING.md
Outdated
| The *strawman* stage captures described problems or partially-considered | ||
| solutions which lack the entrance criteria to be considered a *proposal*. A | ||
| *strawman* may be an issue or a pull request (though an illustrative pull | ||
| request is preferrable). |
There was a problem hiding this comment.
Thesis: RFC with goal of comments
Requirements: very little
Why: To bring attention to issues and/or seek advice on solutions.
A *strawman* RFC captures described problems or partially-considered
solutions. The *strawman* does not need to meet the *proposal* entrance
criteria. A *strawman* may be an issue or a pull request (though an
illustrative pull request is preferrable).
ISSUE_TEMPLATE.md
Outdated
|
|
||
| Instead, find community resources at https://graphql.org/community/ | ||
|
|
||
| # Please do not make feature requests via Issues # |
There was a problem hiding this comment.
Seems like we really don't want people using the "Issues" section.
I can get behind that, but PRs increase the barrier of entrance to the strawman stage.
There was a problem hiding this comment.
Yeah, Issues get ignored much more than PRs, the quality of Issues are typically below that of PRs, and Issues are often drive by requests from people who do not actually intend on following through while those opening PRs tend to follow up :)
I'll think of how to word this a little better - but some amount of creating a barrier for strawman is intentional since we already have ~50 strawman without clear champions in the issues section
This is a top-to-bottom revamp of the Contributing.md document which includes a more thorough and implementable process for identifying what stage a PR is in and what is expected to reach the next stage. It also captures the guiding principles for spec improvements.
Fixes #511