Add Text: Mitigate defects when extending features. #563
Conversation
jyasskin
changed the title
There was a problem hiding this comment.
Thanks for the PR! I have several stylistic requests here, which is to be expected in your first several PRs.
Please write PR titles (and commit messages) to directly explain what's in the PR, since issue references in titles generally don't get linked to the issue, and reading a summary is easier than following a link. The issue link belongs in the body of the PR. I've updated this one, but feel free to change it again if you don't think it's an accurate summary of the PR.
index.bs
Outdated
| As you add new capabilities to the web platform, do so in a way that improves the overall platform, for example its security, privacy or accessibility characteristics. | ||
| The existence of a defect in one part of the platform must not be used to excuse an addition or extension to the defect, which would further decrease the overall platform quality. Consistency is not a good reason to propagate problems. Where possible, build new web capabilities that improve the overall platform quality by mitigating existing defects. Do not degrade existing capabilities without good reason. | ||
|
|
||
| Do not extend a platform feature that has known defects, without considering how to address those defects. Extensions could create new ways in which the defect could cause problems, such as by encouraging more use of the defective feature. It is not necessary to completely fix all aspects of a defect, it is more important to consider mitigations or fixes when developing such an extension. | ||
|
|
||
| Parts of the web platform evolve independently. Issues that are present with a certain web technology now may be fixed in a subsequent iteration. Duplicating these issues makes fixing them more difficult. By adhering to this principle we can make sure overall platform quality improves over time. |
There was a problem hiding this comment.
This document tends to use semantic line breaks. I'm inclined to say that all patches should do that, but even if we decide not to, they should definitely wrap at 80-100 columns.
Also please avoid re-wrapping lines you're not otherwise touching, to make the diff easier to read.
There was a problem hiding this comment.
It looks like my IDE hard wrap setting didn't take effect. Thanks for catching this! I'll add the line breaks and push it back up.
There was a problem hiding this comment.
I think that you missed the intent of the comment.
When using semantic breaks, you attempt to keep one concept per line. That means that lines end on periods and semi-colons always, and at the end of obvious clauses. (This is not a good idea with GitHub markdown, which retains line breaks, BTW.)
That means not doing a hard wrap at any particular column (like your 100ch), but choosing where to break deliberately.
index.bs
Outdated
| Duplicating these issues makes fixing them more difficult. | ||
| By adhering to this principle we can make sure overall platform quality improves over time. | ||
| As you add new capabilities to the web platform, do so in a way that improves the overall platform, for example its security, privacy or accessibility characteristics. | ||
| The existence of a defect in one part of the platform must not be used to excuse an addition or extension to the defect, which would further decrease the overall platform quality. Consistency is not a good reason to propagate problems. Where possible, build new web capabilities that improve the overall platform quality by mitigating existing defects. Do not degrade existing capabilities without good reason. |
There was a problem hiding this comment.
I think the only new thing in this paragraph is the sentence about consistency. I think we need to be more nuanced about that, since https://w3ctag.github.io/design-principles/#consistency says consistency is a good reason to propagate certain problems. I'm not sure exactly what to suggest, but I'll keep thinking about it.
index.bs
Outdated
| As you add new capabilities to the web platform, do so in a way that improves the overall platform, for example its security, privacy or accessibility characteristics. | ||
| The existence of a defect in one part of the platform must not be used to excuse an addition or extension to the defect, which would further decrease the overall platform quality. Consistency is not a good reason to propagate problems. Where possible, build new web capabilities that improve the overall platform quality by mitigating existing defects. Do not degrade existing capabilities without good reason. | ||
|
|
||
| Do not extend a platform feature that has known defects, without considering how to address those defects. Extensions could create new ways in which the defect could cause problems, such as by encouraging more use of the defective feature. It is not necessary to completely fix all aspects of a defect, it is more important to consider mitigations or fixes when developing such an extension. |
There was a problem hiding this comment.
We should probably say something stronger than "consider". Maybe use "should" in a more direct sentence about partially fixing the defects, since that allows exceptions when justified?
|
@martinthomson I know you had ideas around wording for this in Paris, just wanted to draw your attention to the PR. |
index.bs
Outdated
| Parts of the web platform evolve independently. Issues that are present with a certain web | ||
| technology now may be fixed in a subsequent iteration. Duplicating these issues makes fixing them | ||
| more difficult. By adhering to this principle we can make sure overall platform quality improves | ||
| over time. |
There was a problem hiding this comment.
I don't understand why the "independence" point was added. I read it as weakening the message, rather than strengthening it.
There was a problem hiding this comment.
I copied & pasted the text from the minutes taken in Paris so don't remember who suggested it specifically. Maybe it'd be helpful to bring to the group on Slack/breakout?
lolaodelola
changed the title
This is the discussed draft text for issue #514.
Preview | Diff