MSC2618: Helping others with mandatory implementation guides #2618
Conversation
turt2live
changed the title
turt2live
added
kind:core
|
|
||
| MSCs which are self-documenting, such as the small/tiny maintenance ones, or which do not affect the | ||
| spec featureset, like this one, do not need to have implementation considerations documented. However, | ||
| it would be greatly appreciated if the redundancy was present for the sake of clarity. |
There was a problem hiding this comment.
By redundancy here, you mean that the MSC author should include some existing steps surrounding the feature they're modifying?
There was a problem hiding this comment.
ish, yea. Basically if your MSC is "We should mandate that all text is purple" the implementation considerations should say "All text is now purple".
There was a problem hiding this comment.
Ahh, I see. This paragraph means redundancy between what you wrote and the implementation guide. I thought it was referring to redundancy with existing content in the implementation guide/other MSCs.
| Anyone who plans on implementing an MSC should be prepared to document their issues for other implementations | ||
| to consider. This may add time to the development of a feature, however the greater ecosystem will benefit | ||
| more from the issues being recorded. Likewise, MSC authors should be made aware when their MSC is being | ||
| implemented and be prepared to document any common questions they receive as considerations. |
There was a problem hiding this comment.
Is this true even if the MSC has already been merged?
There was a problem hiding this comment.
merged or landed? If it's merged then we have a problem.
There was a problem hiding this comment.
I'm actually not sure what the difference is between "merged" and "landed".
I mean the MSC itself has been merged into the proposals/ folder, a spec PR could still be absent.
There was a problem hiding this comment.
That is landed. Merged is a specific status for when a spec PR has been accepted and a spec release performed.
There was a problem hiding this comment.
Ahhh, ok, I see what you're saying now.
So... is this true even when an MSC has landed? :) I guessing this is true and someone's responsibility up until the MSC is merged.
There was a problem hiding this comment.
Yup. It's no different than the requirement to keep the MSC updated with changes.
There was a problem hiding this comment.
Cool. I think this point and the other one could use some light clarification in the document? Otherwise the rest of it looks good to me.
|
|
||
| ## Alternatives | ||
|
|
||
| We sit in sadness for lack of documentation, leading to frustrated developers and abandoned implementations. |
There was a problem hiding this comment.
On a more serious note, the alternative could be to continue filling the spec documents with implementation advices. The downside of that is described in the introduction, as this is business as usual to some extent.
turt2live
added
the
needs-implementation
Rendered