search

whatwg / meta

Discussions and issues without a logical home
Creative Commons Zero v1.0 Universal
96 stars 161 forks source link

MDN issue process #334

Open Josh-Cena opened 6 days ago

Josh-Cena commented 6 days ago

Hello, I'm one of the maintainers of mdn/content. I'm sending the issue in the context of https://github.com/mdn/content/issues/36464.

I think at least two revisions should be made about the current MDN issue process:

  1. We have two repositories for tracking issues: https://github.com/mdn/content, https://github.com/mdn/mdn. The former is for granular, actionable items that affect only one or a few pages. For example, changing the default value of a parameter (such as notification silent default), modifying behavior (such as URL parsing), or adding a single attribute/method/etc (such as <input type="checkbox" switch>). These are more likely to be picked up by community contributors. The latter is for bigger projects that involve many pages, such as the addition of a new API surface (including https://github.com/mdn/content/issues/36464). These require concerted effort and likely need a maintainer to champion the work.

    I noticed that many WHATWG contributors are already filing issues to mdn/mdn, most likely because our issue chooser wizard recommends using that repo for feature requests. I'd like this to be formalized in the maintainer docs. In terms of semantic commits, think about it as "feat PRs go to mdn/mdn, while fix/polish/refactor/etc. go to mdn/content".

  2. This is more of a pet peeve of mine, and I haven't discussed it with other maintainers, but: while I appreciate WHATWG's attention to MDN's up-to-datedness, I think the doc issues are filed too early in the process. For example, https://github.com/mdn/content/issues/21912 will soon have its 2nd birthday, but its whatwg/html PR is still open, let alone having two stable implementations. I wonder if it's too much to ask, but I would like MDN issues to be filed after vendor bugs, not with vendor bugs—preferably, they would only appear when there are actual implementations (which is, AFAIK, around the time the PR gets merged), since that's when we can actually document them. Right now, we add the "waiting for implementations" label for WHATWG issues, but this still puts unactionable issues in our queue.

I will forward this discussion to other MDN maintainers. Happy to have more discussions and/or review changes to the WHATWG docs w.r.t. MDN process.

annevk commented 6 days ago

I don't think we can do 2. There's no point in our process where we'd evaluate those implementer bugs getting resolved. You could leave it entirely to implementers, but I suspect they wouldn't file a documentation issue most of the time.

Josh-Cena commented 6 days ago

It's better to send issues early than not send them at all. Our second checkpoint is when Firefox implements it since the Mozilla docs team works on MDN, but that may be too late. If the WHATWG process does not take implementation status into account, then sure the current way seems best.

annevk commented 6 days ago

cc @whatwg/documentation