1278516 - Update specification list, {{SpecName}} and {{spec2}} to make draft link and status consistent

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: Macros/Templates, defect)

Description

[Sebastian Zartner [:sebo]]

As described in a dev-mdc discussion[1][2] the data in {{spec2}} and {{SpecName}} should be kept consistent. That is, if there are a living standard and a recommendation, both should be listed inside the templates and the pages referring to them need to be updated accordingly.

This is currently not true for some HTML related specifications, for the Selectors API L2 and the Progress Events.

The page and templates that need to be adjusted are:
https://developer.mozilla.org/en-US/docs/Template:Spec2
https://developer.mozilla.org/en-US/docs/Template:SpecName
https://developer.mozilla.org/en-US/docs/Web/Specification_list

Sebastian

[1] https://groups.google.com/d/topic/mozilla.dev.mdc/q9ABki6Spdg/discussion
[2] https://groups.google.com/d/topic/mozilla.dev.mdc/HRKAE8NUaIs/discussion

Comment 1

[Jean-Yves Perrier [:teoli]]

Looks like a good idea. SebastianZ, can you list here the specs that are missing?

Comment 2

[Sebastian Zartner [:sebo]]

(In reply to Jean-Yves Perrier [:teoli] from comment #1)
> Looks like a good idea. SebastianZ, can you list here the specs that are
> missing?

Setting ni to myself to not forget it. I'll need a bit to go through the specs to check the ones that are missing.

Sebastian

Comment 3

[Sebastian Zartner [:sebo]]

Below are the results of my analysis. Jean-Yves, please verify whether that's ok for you.

- Selectors API Level 2:
  WG Note, https://www.w3.org/TR/selectors-api2/, APIs moved to DOM4 (REC)/DOM WHATWG (LS)
  spec2 says WD *WRONG*
  => spec2 should say WG Note or the entry should be removed;
  (pages should refer to Selectors API Level 2 or it should be removed accordingly)

- Progress Events:
  REC, https://www.w3.org/TR/progress-events/, APIs moved to XMLHttpRequest
  spec2 says CR, SpecName links to https://xhr.spec.whatwg.org/ *WRONG*
  => spec2 should say REC and SpecName link to https://www.w3.org/TR/progress-events/, specification list should merge 'Progress Events' and 'XMLHttpRequest';
  (pages need to be adjusted to include both 'Progress Events' and 'XMLHttpRequest')

- Web Storage:
  REC, https://www.w3.org/TR/webstorage/, also part of HTML WHATWG (LS)
  spec2 says REC, SpecName links to https://html.spec.whatwg.org/multipage/webstorage.html *WRONG*
  => SpecName should link to https://www.w3.org/TR/webstorage/, new 'Web Storage WHATWG' entry should be added with spec2 saying 'Living' and SpecName linking to https://html.spec.whatwg.org/multipage/webstorage.html, specification list needs to be changed to link to both 'Web Storage' and 'Web Storage WHATWG';
  (pages should refer to both 'Web Storage' and 'Web Storage WHATWG')

- HTML5 Web Messaging:
  REC, https://www.w3.org/TR/webmessaging/, also part of HTML WHATWG (LS), https://html.spec.whatwg.org/multipage/comms.html#web-messaging and https://html.spec.whatwg.org/multipage/comms.html#channel-messaging
  SpecName links to https://w3c.github.io/webmessaging/ *WRONG*
  => SpecName should link to https://www.w3.org/TR/webmessaging/, new 'Communication' entry should be added with spec2 saying 'Living' and SpecName linking to https://html.spec.whatwg.org/multipage/comms.html, specification list needs to be changed to link to both 'HTML5 Web Messaging' and 'Communication';
  (pages need to be adjusted to include both 'HTML5 Web Messaging' and 'Communication')

- Web Workers:
  WD, https://www.w3.org/TR/workers/, also part of HTML WHATWG (LS), https://html.spec.whatwg.org/multipage/workers.html
  spec2 says ED, SpecName links to https://w3c.github.io/workers/ *WRONG*
  => spec2 should say WD and SpecName link to https://www.w3.org/TR/workers/, new 'Web Workers WHATWG' entry should be added with spec2 saying 'Living' and SpecName linking to https://html.spec.whatwg.org/multipage/workers.html, specification list needs to be changed to link to both 'Web Workers' and 'Web Workers WHATWG';
  (pages need to be adjusted to include both 'Web Workers' and 'Web Workers WHATWG')

- Websockets:
  CR, https://www.w3.org/TR/websockets/, also part of HTML WHATWG (LS), https://html.spec.whatwg.org/multipage/comms.html#network
  SpecName links to https://w3c.github.io/websockets/ *WRONG*
  => SpecName should link to https://www.w3.org/TR/websockets/, new 'Web Sockets WHATWG' entry should be added with spec2 saying 'Living' and SpecName linking to https://html.spec.whatwg.org/multipage/comms.html#network, specification list needs to be changed to link to both 'Websockets' and 'Web Sockets WHATWG';
  (pages need to be adjusted to include both 'Websockets' and 'Web Sockets WHATWG')

- Server-sent events:
  REC, https://www.w3.org/TR/eventsource/, also part of HTML WHATWG (LS), https://html.spec.whatwg.org/multipage/comms.html#server-sent-events
  SpecName has 'Server-sent events 2' linking to http://www.w3.org/TR/eventsource/ *WRONG*
  => 'Server-sent events WHATWG' should be added to spec2 and say Living,'Server-sent events 2' in SpecName should be replaced by 'Server-sent events WHATWG' and link to https://html.spec.whatwg.org/multipage/comms.html#server-sent-events, specification list needs to be changed to link to both 'Server-sent events' and 'Server-sent events WHATWG';
  (pages need to be adjusted to include both 'Server-sent events' and 'Server-sent events WHATWG')

Sebastian

Comment 4

[Jean-Yves Perrier [:teoli]]

Here are my answers
* Selector API 2
  -> Remove and use DOM 4 *and* DOM WhatWG (2 lines
* Progress Event
  -> Yes, with this additional detail: do not link to TR if there is an editor draft of the same version still existing.
* Web Storage
  -> Yes, with the same additional detail about TR.
* HTML5 Web Messaging
  -> Yes, with the same additional detail about TR.
* Web Workers
  -> Yes, with the same additional detail about TR.
* WebSockets
  -> Yes, with the same additional detail about TR.
* SSE
  -> Yes, with the same additional detail about TR.

Just go ahead! Looks great!

Comment 5

[Sebastian Zartner [:sebo]]

Sorry for the delay on this! I rethought this and would like to make some changes to what I wrote before.

(In reply to Jean-Yves Perrier [:teoli] from comment #4)
> Here are my answers
> * Selector API 2
>   -> Remove and use DOM 4 *and* DOM WhatWG (2 lines
> * Progress Event
>   -> Yes, with this additional detail: do not link to TR if there is an
> editor draft of the same version still existing.

Note that the specs do *not* have editor drafts anymore. Instead, they link to the living standard documents.
Therefore, I think it's ok to link them to TR.

> * Web Storage
>   -> Yes, with the same additional detail about TR.
> * HTML5 Web Messaging
>   -> Yes, with the same additional detail about TR.
> * Web Workers
>   -> Yes, with the same additional detail about TR.
> * WebSockets
>   -> Yes, with the same additional detail about TR.
> * SSE
>   -> Yes, with the same additional detail about TR.

Because all of the above got merged with the HTML Living Standard, it probably makes more sense to refer to the existing 'HTML WHATWG' entry instead of adding new entries for them. What do you think? 

Sebastian

Comment 6

[Sebastian Zartner [:sebo]]

(In reply to Jean-Yves Perrier [:teoli] from comment #4)
> Here are my answers
> * Selector API 2
>   -> Remove and use DOM 4 *and* DOM WhatWG (2 lines

Btw. as removing would break existing pages - and there are many referring to it and I have no possibility to search for e.g. "{{spec2("Selectors API Level 2")}}" within all pages - I consider to only add a note about its deprecation as a first step, so the removal from the pages can be done asynchronously. We may create bugs blocking this one to track the removal. Good idea?

Sebastian

Comment 7

[Jean-Yves Perrier [:teoli]]

Yes, for the specs that have been merged into HTML Living Standard, I see:

- When they have reached Rec, list the TR of the Rec spec, and the HTML Living Standard (and eventual HTML5.x W3C snapshots)
- When they have *not* reached Rec before being merged in the HTML LS, list only HTML LS (and eventual HTML5.x W3C snapshots)

For Selector API 2, I think separating the deprecation and the removal is a good idea.

Comment 8

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.