Improve description of what belongs in a proposal document versus in the design #649
Conversation
…the design Expand the description of the structure of a proposal PR. Clarify that the full PR is the proposal, not only the P-numbered document. Start a design style guide and use it to describe which parts of a proposal should not end up in the design.
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
purpose of docs/design.
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
There was a problem hiding this comment.
FWIW, this is really nice, and thanks for writing it up.
Comments below are honestly pretty minor. If they make sense, land it. If I've just missed something, let me know and land it. Either way, LGTM. Of course, if there is something confusing here, of course, happy to chat and clairfy.
I'm also approving as I think this is pretty much clarifying the process and not a significant change. As a result, I think its fine to go ahead and land and iterate here. But we should definitely iterate if @KateGregory has any other feedback as a lead -- I think its good for all three of us to have read this in a reasonable amount of detail and be happy.
docs/project/design_style_guide.md
Outdated
| - Proposal [#123](https://github.com/carbon-language/carbon-lang/pull/123): | ||
| widget painting. |
There was a problem hiding this comment.
(minor)
Again guessing we should use a large linked text to be accessible / easy to find. (That said, I'm not an expert and am just guessing -- maybe I'm wrong about what is most useful here?)
| - Proposal [#123](https://github.com/carbon-language/carbon-lang/pull/123): | |
| widget painting. | |
| - [Proposal #123: Widget painting.](https://github.com/carbon-language/carbon-lang/pull/123) |
There was a problem hiding this comment.
FWIW, it might be worth thinking here about what we could, in theory, automate:
- We can definitely automate detecting
#123and suggesting[#123](https://github.com/carbon-language/carbon-lang/issues/123), just turning it into a link.- Note here that linking
issuesinstead ofpullallows it to be either an issue or a PR. This kind of link works in both cases.
- Note here that linking
- We can sort of automate suggesting
[#123: Widget painting](https://github.com/carbon-language/carbon-lang/pull/123)by detecting the#123in a link, looking for the corresponding proposal file, reading the title, etc. This may be fragile if somebody points at an in-flight proposal (or issue).- It couldn't accurately capture surrounding text, e.g. if somebody wrote
#123: the painting proposalwithout a link and with a non-matching description. You'd end up with[#123: Widget painting](...): the painting proposal.
- It couldn't accurately capture surrounding text, e.g. if somebody wrote
- We could also get into github APIs and read from the server for something more durable, at the cost of creating server RPCs as part of formatting, but I worry about running repeated server RPCs from pre-commit. I'd advise against this.
- Formatting as suggested here would require formatting any link matching
.*\W#\d+\W.*which may be a little too flexible.
There was a problem hiding this comment.
What I've gone with for now is to make including the title of the proposal optional in the link text. For automation purposes, we can detect existing links of the form "[#NNN..." and make sure they link to the right place, and can form links from text #NNN, but can't easily include a following ": ..." in the link nor automatically add one. We can probably do better, but I think we can handle any further improvement incrementally from this starting point.
| proposal would then be implemented through a series of future PRs to the rest of | ||
| the project, and the proposal document should describe what is being proposed in | ||
| enough detail to validate that those future PRs properly implement the proposed | ||
| direction. |
There was a problem hiding this comment.
I feel like we should have some statement explicitly saying that the quality standard for proposal documents are lower.
…n versus in a proposal document. (#649) Expand the description of the structure of a proposal PR. Clarify that the full PR is the proposal, not only the P-numbered document. Start a design style guide and use it to describe which parts of a proposal should not end up in the design. Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com> Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Expand the description of the structure of a proposal PR. Clarify that the full PR is the proposal, not only the P-numbered document. Start a design style guide and use it to describe which parts of a proposal should not end up in the design.