Notify MDN about changes about meta HOT 23 CLOSED

Sorry for being so slow to get to this thread. Xmas vacation and all ;-)

So my thoughts are that it'd be great to have a way of picking up spec changes that will eventually require documentation changes. This could be the single source of truth, rather than docs changes being identified sometimes by Mozilla, sometimes by Google, sometimes by MS, etc., on our individual bug trackers. Having a single point of truth seems more efficient to me.

Of course, then we'd have to prioritise documenting these things, which would require checking which things are currently (being) implemented against the bug trackers anyway. This might make it not so efficient after all, unless we could automate it all in one stroke.

I am going to bring this up as a discussion topic at the next MDN product advisory board meeting, to get input from multiple browser vendors on how this could work.

To answer @snuggs, there has no movement on this, but we have certainly talked about moving all of MDN (including all the document content) onto GitHub. The PR model would offer a lot of advantages over our current Wiki model...I can't say much more on this yet though.

from meta.

@chrisdavidmills note that at least for WHATWG Living Standards, the intention is that changes will be picked up by at least two implementation in a short period. We secure implementation support before making changes, effectively.

from meta.

@annevk OK, cool - this is useful to consider.

from meta.

As for how to know when it's worth documenting, one signal that we could automate is the tests. Since the PRs are normally linked to tests, we could track when those tests begin to pass in any browser take some action, like poke a PR maybe.

from meta.

I really like this, I've found it tough to remember change/update some MDN stuff in the past.

from meta.

Maybe "needs documentation" to match some of the other labels?

@jpmedley, WDYT?

from meta.

@foolip My only concern with that is, to me it almost indicates we’d block merging on waiting for documentation. Do we want this, and do others perceive it that way or is that just me?

I think something like mdn-relevant or effects-documentation is nice because it’s more of a side note for external parties to track and us not to worry about TOO much. Thoughts?

from meta.

The other needs foo labels are blocking, so yes, that's a problem. But if this is a label that will be tracked after issues have already been closed, then removing mdn-relevant also seems weird. It's still relevant :)

Maybe two labels would be better, so that no labels are removed. No ideas about names though.

from meta.

It wouldn't be removed though. It would just stay there. (Modifying labels is tricky in this case as MDN folks are unlikely to have the required GitHub access. That's why we came up with the above suggestion.)

from meta.

How would triage work if no state on our issues changes after the thing has been documented?

from meta.

Yeah I feel like we can either have a single label that gets removed from closed issues/PRs once MDN'ers update documentation, or the two labels as @foolip recommends - as in, we add a label like "documentation-addressed/complete" or something when the documentation catches up.

The issue I see with the two-label solution is that it requires MDN'ers that wish to find PRs that require documentation to manually filter through ones that DON'T also have the "documentation-complete" label. GitHub does not provide a way through the advanced search UI to search for issues/PRs through label exclusion. It can still be done this way but I'm assuming most don't know about it, and it could be helpful with the two-label soln.

from meta.

I don't remember how I discovered that it worked, but we have a triage process for web-platform-tests to look for issues with some labels but without some others in https://bit.ly/ecosystem-infra-rotation. There are a bunch of people who take part in that and AFAIK it hasn't been a problem that the query can't be created by only clicking things.

from meta.

from meta.

I think if you browse https://github.com/whatwg/html/commits/master you'll find very few of those would require MDN updates. On that first page as of today I see 7 (assignedElements, autocapitalize, modulepreload, inputmode, img decoding, hide nonce, remove link rel=serviceworker) out of 35 changes that would probably require such updates.

from meta.

I feel that:

1. There are some spec changes that are editorial or documentation-based in nature like this, though these (and ones similar) are probably vastly outnumbered by normative implementation- and test-affecting changes
2. Even then, the number of implementation- and test-affecting changes might be minor/specific enough to not need a documentation change. As in, since the documentation isn't 1:1 with the spec, even small normative changes might not change anything in more general conceptual documentation.

from meta.

@annevk i've been helping MDN get up to speed on Github with web components and compatibility.
(mdn/browser-compat-data#623, mdn/browser-compat-data#627). Is the intent to have "all" of MDN up on Github repositories?

Thanks for the answer in advance. /cc @chrisdavidmills

from meta.

I think so, long term.

from meta.

from meta.

One problem we'd need to resolve is that if we mark things as resolved by adding or removing a label (1- or 2-label system) then the MDN people would have to be able to change labels in all the spec repos. And that requires write access, it seems.

Would it work to use issues on an MDN repo instead? That is how we handle missing tests, by filing issues on web-platform-tests.

To make that work well in practice I think the issue filing has to be quite streamlined, maybe with a link to a pre-populated issue ready to file?

from meta.

When I talked with @chrisdavidmills we considered that and therefore came up with a single label that MDN folks would track (and MDN would track whether they handled it or not).

from meta.

OK, that'd certainly work from our side. @chrisdavidmills, how would that work on your side? A big spreadsheet that you auto-populate and burn down, or something?

from meta.

@foolip something like that. We already have a big GSheet that we populate using a script from Mozilla's bugzilla when dev-doc-needed keywords are added and the bugs are set to complete, so we could probably do something similar here.

from meta.

I like those ideas. Is the next step on the WHATWG side to add some text in LABELS.md explaining the single label that @annevk alluded to in #62 (comment) ?

from meta.