add proposal document template #1449
Conversation
|
See ☝️ for an example of this template in use. |
|
We're having some debate on the purpose of this document over on #1450. Holding this until that resolves. |
|
Based on the discussion and activity at #1450, I feel this PR needs a suplementary document which explains the purpose of the proposal document (or documents if that turns out to be the case). I would think such discussion needs to be had at #1443 and agreed on before making further changes here. I'm happy to facilitate these discussions, either in text form or via calls. @gregsdennis @jdesrosiers let me know which you would prefer. (Anyone else is also welcome to be involved, but Greg and Jason are the primary individuals driving this right now.) |
| ## Status | ||
|
|
||
| **Current Status**: PROPOSAL | ||
|
|
||
| <!-- TODO: We should have a short standard blurb outlining the stages involved in a | ||
| feature making its way to stable status. --> | ||
|
|
||
| <!-- TODO: Link to a document that describes the proposal => stable process in | ||
| detail. --> |
There was a problem hiding this comment.
Starting to think this can go away completely. The document is a proposal.
Maybe we want to keep it around for posterity, but I think we could use file paths to handle that. Maybe something like moving the files to a completed/<release>/ folder and renaming the file to <filename>-rejected.md / <filename>-accepted.md.
Personally, I'm happy with just deleting the file once we don't need it anymore, whether it was rejected or accepted.
There was a problem hiding this comment.
I think it would be a good idea to use the status field to communicate the maturity of the proposal. For example, something like,
- Development -- The proposal is in the early stages of being considered
- Release Candidate -- No further changes are expected, but we want to see as much implementation and usage to flush out any remaining issues
- Awaiting Release -- The proposal has been excepted and will be included in the next release. There will be no more changes.
- Released
- Rejected
We don't even need to have a fixed list of statuses we're limited to. I think what's important is that it communicate something useful.
As for whether to keep around completed proposals, I think it's best to keep them around. Technically, they're never gone because they're in the git history, but people aren't going to go digging through our git history to find a proposal they're watching. I'm imagining someone trying to find the status of a proposal they're interested in and being confused because they can't find it or any explanation why it disappeared. For the same reason, I think it's best not to move them to a "rejected" or "completed" folder because that would break any bookmarks people have to those proposals. They can maybe be removed after some generous period of time, but not right away.
| ### Alternatives | ||
|
|
||
| <!-- What other options have been considered? (summary, not detailed) --> |
There was a problem hiding this comment.
Per #1443 (comment), maybe this should go. This would be important for an ADR, but it's not necessarily something that the public needs to see.
There was a problem hiding this comment.
I'm still not entirely sure where you want to draw the line between the two documents, but I agree that a discussion of the alternatives isn't necessary in this document except maybe as an appendix.
Resolves #1443
I started working on the
propertyDependenciesextraction and the template kinda just worked itself out. It turns out leaving questions is easier that actually filling out the sections.