Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ruby Markup Coordination #14

Merged
merged 17 commits into from
Feb 10, 2022
Merged

Ruby Markup Coordination #14

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
e294152
Copy text from https://github.com/whatwg/sg/issues/184#issuecomment-9…
frivoal Jan 16, 2022
eee3c7f
Line break the text for easier editing
frivoal Jan 16, 2022
94bae1f
Minor tweaks to adjust the text to its new context
frivoal Jan 16, 2022
a8159b6
Add hyperlinks and abbr title
frivoal Jan 16, 2022
0528c9d
Convert to HTML
frivoal Jan 16, 2022
450d562
Link to the ruby agreement from the README
frivoal Jan 16, 2022
4b19b99
Replace third paragraph
frivoal Jan 20, 2022
38ea6fd
Clarify the goal of pull requests
frivoal Jan 26, 2022
68c5be5
Phrasing tweak on merging PRs
frivoal Jan 26, 2022
7058941
Clarify that this is based on the PR instead of being defined by the PR
frivoal Jan 26, 2022
d654a1d
Phrasing tweak about using the REC track
frivoal Jan 26, 2022
9f476af
Fix typo
frivoal Jan 27, 2022
8e5b44e
Update date in presumed URL
Feb 1, 2022
5fefa6f
Convert leftover markdown to actual html
frivoal Feb 6, 2022
3f67a42
Adopt the rewording proposed by foolip
frivoal Feb 6, 2022
1f3830a
Credit both sources of this work
frivoal Feb 9, 2022
bc3b69a
Merge second and third paragraphs
frivoal Feb 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@

* [Memorandum of Understanding Between W3C and WHATWG](https://www.w3.org/2019/04/WHATWG-W3C-MOU.html)
* [Update, 30 June 2021](https://www.w3.org/2021/06/WHATWG-W3C-MOU_2021_update.html)
* [Agreement on HTML Ruby Markup](https://www.w3.org/2022/01/ruby-agreement)
5 changes: 5 additions & 0 deletions ruby/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Agreement on HTML Ruby Markup

This directory contains:

* an exact copy of the Agreement on HTML Ruby Markup
45 changes: 45 additions & 0 deletions ruby/ruby-agreement.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Agreement on HTML Ruby Markup</title>
<style>
body {
max-width: 50em;
margin: auto;
font-family: sans-serif;
}
</style>

<h1>Agreement on HTML Ruby Markup</h1>

<p>
The W3C will specify the extended HTML Ruby markup
described in <a href="https://github.com/whatwg/html/pull/6478">PR#6478</a>
as a <a href="https://www.w3.org/Consortium/Process/#rec-track">REC track</a> document.
The W3C and WHATWG believe this is within the bounds of our <a href="https://www.w3.org/2019/04/WHATWG-W3C-MOU">MoU</a>,
and while it is not the ideal outcome
(having Ruby documented in two places),
we understand that it serves the goals for the W3C’s constituencies and existing implementations
to have an easily referencable document
as well as honoring the strict <a href="https://whatwg.org/working-mode#additions">requirements of the WHATWG</a>
that the living standard not contain new additions
that don’t have multi-browser-engine implementer commitments.

<p>
The <abbr title="Status Of This Document">SOTD</abbr> section of the W3C Ruby Extension spec
will state our joint intention
that the extended ruby markup definitions be fully integrated into the <a href="https://html.spec.whatwg.org/multipage/">WHATWG HTML specification</a>
once they <a href="https://whatwg.org/faq#adding-new-features">meet WHATWG’s inclusion criteria</a>
under section <a href="https://www.w3.org/2019/04/WHATWG-W3C-MOU#forking">10.2 of the 2019 MOU</a>.

<p>
W3C editors will offer pull requests
to keep the HTML spec in sync,
both technically and editorially,
for the subset of features defined in both specs
(goal is to reduce the deltas
such that the only differences will be
the addition of the two new elements <code>&lt;rb></code> and <code>&lt;rtc></code>);
WHATWG HTML editors will work with the W3C Ruby Extension spec authors
to merge those pull requests in support of that goal.
Copy link

@domenic domenic Jan 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I think this is a good suggestion that works a reasonable balance between what everybody has expressed so far.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me know if this is now acceptable and ready to merge