Ruby Markup Coordination #14
Conversation
(No change to the textual content)
The text was originally written with "we" representing the WHATWG, but here, we represents the WHATWG and the W3C jointly. Also, the text originally expressed intent to agree, which can now be rephrased as actual agreement.
(No change to the textual content)
(No change to the textual content)
Use the probable publication URL in the README. To be changed if this is ultimately published elsewhere.
ruby/ruby-agreement.html
Outdated
| such that the only differences will be | ||
| the addition of the two new elements <code><rb></code> and <code><rtc></code>); | ||
| WHATWG HTML editors will work with the W3C Ruby Extension spec authors | ||
| to merge those pull requests in support of that goal. |
There was a problem hiding this comment.
This doesn't seem quite right. We (WHATWG HTML editors) have expressed a few times that our goal is not to reduce deltas in such a way; instead we are hoping that we will get surgical contributions which correct any not-implemented-in-two-browsers issues with the current algorithm, accompanied by web platform tests, per our working mode. Large PRs rewriting the ruby sections to be based on a new document aren't something we'd be interested in, and it shouldn't be stated that we will merge them.
There was a problem hiding this comment.
I think that's reasonable... and is likely otherwise less work for W3C editors. How about changing the paragraph to something like:
W3C editors may offer pull requests that correct existing Ruby algorithms for which browser implementations are not aligned, along with accompanying web platform tests per WHATWG working mode process. It is not expected that the W3C document and WHATWG spec content be kept in sync prior to being fully integrated under the conditions noted previously. WHATWG HTML editors will evaluate and optionally merge such PRs on their individual merit.
?
There was a problem hiding this comment.
This would be
- More complicated editing work for the W3C editors, because they would need to keep two things normatively synchronized which are not editorially synchronized.
- Many hours of additional effort to explain the nuances of each minor adjustment and clarification to the prose in order to justify each individual change as an improvement, instead of simply defending the correctness of a complete rewrite and the editorialness or correctness of any subsequent fixes.
- Confusing to readers and implementers, because it would not be obvious what the normative differences are between the two specs.
- A disservice to WHATWG readers, because improvements to examples and to the prose's readability will not be available to them. (And improvements are needed, this part of the spec is not well-written and its examples are not particularly well-explained, nor all necessarily good practice.)
So I don't think that's a positive change to our agreement.
Florian and I are willing to submit PRs for full synchronization changes, as agreed with the Steering Group. If WHATWG wants to backtrack on our agreement and not merge them, well, we believe it's a poor decision but can probably live with it: having the rest of the agreement still moves us forward. But in that case we'll leave the work of maintaining this section of the WHATWG spec to the WHATWG editors.
However, we would rather see this section of the WHATWG spec be something people want to reference, rather than being a poorly-explained shadow of the W3C spec.
There was a problem hiding this comment.
It seems like there are larger disagreements here on the direction that were not discussed. I don't think this is quite at the "agreement" stage yet, in that case.
There was a problem hiding this comment.
In particular the unwillingness to do extra complicated editing work and explanation is disappointing, and not the spirit I thought this agreement was in. Just lobbing changes over and expecting them to be accepted without evaluation, explanation, or collaboration is not a reasonable way to interface with the WHATWG.
There was a problem hiding this comment.
Yeah, I think the fact that this is REC-track and has a rather long history is why it's good to have something explicit. And also what makes it unusual. I wouldn't want a whole slew of REC-track documents extending HTML.
In general I'd lean towards preserving the existing text, except where it has a known problem of sorts. Rewrites can come with unintended bugs, much like software rewrites.
There was a problem hiding this comment.
I think the most important thing here is that we document in public that the WHATWG acknowledges that the Ruby extension spec exists, that there has been "good faith negotiation" and that this not considered a fork outside the bounds of the MoU. The first paragraph achieves that.
When it comes to what changes will be made to the HTML spec, would it be acceptable to state that there will be good faith collaboration, while following our usual working mode? Suggestion:
W3C editors may offer pull requests to keep the HTML spec in sync, both technically and editorially, for the subset of features defined in both specs. WHATWG HTML editors will review these contributions in good faith, following the WHATWG working mode.
Unstated would be that if collaboration breaks down, appealing to the SG is still possible.
I recognize it would be nice to agree up front on what the HTML spec's Ruby section is going to be like, but it sounds like that will depend on the amount of time and effort that the W3C+WHATWG editors thinks it's worth when getting into the details.
There was a problem hiding this comment.
Thanks, I think this is a good suggestion that works a reasonable balance between what everybody has expressed so far.
There was a problem hiding this comment.
I have just pushed new commits. The first is simply drops the original third paragraph and replaces it with the one @foolip just suggested.
After that, as long as we're making some adjustments, I have included a few more minor wording tweaks for the sake of clarity. I believe they do make no difference to the what we are agreeing to, merely make the text easier to understand and help steer clear of undesired implications. For ease of review, each change is a separate commit, with the justification in the commit message.
There was a problem hiding this comment.
Let me know if this is now acceptable and ready to merge
Drop the original third paragraph, since there's no consensus on it after all. Instead, add the alternative third paragraph suggested by foolip in w3c#14 (comment)
Clarify phrasing: the pull requests would be merged following review, not just reviewed for fun. :)
This avoids the implication that we would be strictly confined to the content of the pull request, as we may need to make changes based on feedback.
This is to avoid implying that we cannot handle this as multiple REC track documents rather than a single one, for example in case we need to split into Level 2 and Level 3 (which seems likely based on the differing state of implementations of rb and rtc).
|
I looks like we're now in agreement. (yay!) Can we have the explicit sign-off of the SG as a whole? I have no particular preference between either each member individually vs one member representing the position of the SG collectively. |
|
I'm sorry to introduce another round of changes, but there are parts of this I'd like to change. I'd like to clarify that we agree to to publishing a derived work, using language very close to the MoU. And I want it to be clearer that the HTML editors aren't pre-committed to fully integrating the text, but that our normal working mode will be followed. I've discussed with @othermaciej, @travisleithead and @domenic, and I've drafted this alternative:
This is intentionally rather dry, as I'd like to leave it implementers to say what they intend or hope. But if there's some background you'd like to add back, I'd be fine with that. The "derived document with some textual copying" bit seems important, since it's the reason that the MoU comes into play. I checked whatwg/html#6478 to confirm that there is in fact some text in common still. But I would be happy with some addition pointing out that it's almost entirely rewritten. |
|
@foolip's text works for me. |
|
Looks acceptable to me. I've got two primarily editorial comments:
Lmk if those tweaks are acceptable to you; I'm OK either way, but would prefer to include them. :) |
|
I support @fantasai's suggestions (but I am also still OK even if they are rejected, this is editorial). |
|
Both of @fantasai's suggested edits look good to me. |
|
Looks good to me (including with suggestions) |
|
@travisleithead shouldn't at least @plehegar or @wseltzer have chimed in here? |
|
Yes, we need to chime into this. It's on our list of things to deal with. Should get done next week. |
| Once the <a href="https://whatwg.org/working-mode#additions">criteria for addition</a> to WHATWG Living Standards are met, | ||
| W3C editors may also offer pull requests to fully integrate the extended ruby markup definitions | ||
| into WHATWG HTML. | ||
| WHATWG HTML editors will review these contributions in good faith, | ||
| and merge those they deem acceptable | ||
| under the WHATWG <a href="https://whatwg.org/working-mode">working mode</a>. |
There was a problem hiding this comment.
We'd like to propose a rewording:
In the event that W3C editors offer pull requests to fully integrate the extended ruby markup definitions into WHATWG HTML, once the <a href="https://whatwg.org/working-mode#additions">criteria for addition</a> to WHATWG Living Standards are met, WHATWG HTML editors will review these contributions in good faith, and merge those they deem acceptable under the WHATWG working mode.
There was a problem hiding this comment.
@plehegar I can't tell what this rewording is accomplishing, and I think it's harder to read. Can you explain what the problem is you're trying to solve?
If it's only aesthetic, can we please just keep the current wording?
There was a problem hiding this comment.
Linking the two clauses avoids the implication that W3C editors couldn't offer PRs without the agreement.
There was a problem hiding this comment.
| <h1>Agreement on HTML Ruby Markup</h1> | ||
|
|
||
| <p> | ||
| The W3C will specify extended HTML Ruby markup |
There was a problem hiding this comment.
This should read:
The W3C has the option to specify extended HTML Ruby markup
since we can't commit to do this without proper AC Review of the charter and HTML Working Group approval.
There was a problem hiding this comment.
@plehegar Can we just switch “will” to “may” here rather than complicating the phrasing?
Explicitely use RFC2119 “MAY” when referring to things that are optional, and link to RFC2119 for clarity In response to w3c#14 (comment) and w3c#14 (comment)
Explicitly use RFC2119 “MAY” when referring to things that are optional, and link to RFC2119 for clarity In response to w3c#14 (comment) and w3c#14 (comment)
This prepares the text of the ruby markup agreement outlined in whatwg/sg#184 (comment), with some minor tweaks to account for the fact that the text was originally written with “we” representing the WHATWG, but here, “we” represents the WHATWG and the W3C jointly; Also, the text originally expressed intent to agree, which can now be rephrased as actual agreement.
This is written with the expectation that it'll be published under the w3.org domain, with the copy in this repo service as the source of that official version, for archival and URL persistency reasons, as was done for the MoU.