You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<li><ahref="#expose-everywhere"><spanclass="secno">10.3</span><spanclass="content">Only purely computational features should be exposed everywhere</span></a>
878
878
<li><ahref="#new-data-formats"><spanclass="secno">10.4</span><spanclass="content">Add new data formats properly</span></a>
879
-
<li><ahref="#using-http"><spanclass="secno">10.5</span><spanclass="content">Consult documentation on best practices when using HTTP</span></a>
880
-
<li><ahref="#extend-manifests"><spanclass="secno">10.6</span><spanclass="content">Extend existing manifest files rather than creating new ones</span></a>
881
-
<li><ahref="#serialization"><spanclass="secno">10.7</span><spanclass="content">Consider consumers when serializing</span></a>
882
-
<li><ahref="#debuggability"><spanclass="secno">10.8</span><spanclass="content">Ensure features are developer-friendly</span></a>
883
-
<li><ahref="#crypto"><spanclass="secno">10.9</span><spanclass="content">Use the best crypto, and expect it to evolve</span></a>
884
-
<li><ahref="#client-hints"><spanclass="secno">10.10</span><spanclass="content">Do not expose new information through Client Hints</span></a>
879
+
<li><ahref="#extend-manifests"><spanclass="secno">10.5</span><spanclass="content">Extend existing manifest files rather than creating new ones</span></a>
880
+
<li><ahref="#serialization"><spanclass="secno">10.6</span><spanclass="content">Consider consumers when serializing</span></a>
881
+
<li><ahref="#debuggability"><spanclass="secno">10.7</span><spanclass="content">Ensure features are developer-friendly</span></a>
882
+
<li><ahref="#crypto"><spanclass="secno">10.8</span><spanclass="content">Use the best crypto, and expect it to evolve</span></a>
883
+
<li><ahref="#client-hints"><spanclass="secno">10.9</span><spanclass="content">Do not expose new information through Client Hints</span></a>
885
884
</ol>
886
885
<li>
887
886
<ahref="#spec-writing"><spanclass="secno">11</span><spanclass="content">Writing good specifications</span></a>
@@ -1290,12 +1289,13 @@ <h3 class="heading settled" data-level="2.5" id="specs-include-guidance"><span c
<p><spanid="using-http"><adata-biblio-display="inline" data-link-type="biblio" href="https://httpwg.org/specs/rfc9205.html"><cite>Building Protocols with HTTP</cite></a></span>,
1294
+
especially on <ahref="https://httpwg.org/specs/rfc9205.html#section-4.7">defining header fields</a>, and <ahref="https://datatracker.ietf.org/doc/search?name=HTTP&sort=&rfcs=on&by=group&group=httpbis">other HTTP RFCs</a></p>
<p>Consistency with other parts of the Web Platform is important,
1705
1705
even if this means using another character to separate values.</p>
1706
-
<divclass="example" id="example-ca508580">
1707
-
<aclass="self-link" href="#example-ca508580"></a>
1706
+
<divclass="example" id="example-03f014a3">
1707
+
<aclass="self-link" href="#example-03f014a3"></a>
1708
1708
<p>The <code><adata-link-type="element-sub" href="https://html.spec.whatwg.org/multipage/input.html#attr-input-accept" id="ref-for-attr-input-accept">accept</a></code> attribute is a comma-separated list of values,
1709
-
because it needs to match the syntax of the <code>Accept</code> HTTP header. (See <ahref="#using-http">guidance on HTTP headers</a>)</p>
1709
+
because it needs to match the syntax of the `<code><adata-link-type="http-header" href="https://www.rfc-editor.org/rfc/rfc9110.html#name-accept" id="ref-for-name-accept">Accept</a></code>` HTTP header.</p>
1710
1710
</div>
1711
1711
<p>Regardless of syntax, attributes should only be used for short lists of values.
1712
1712
For longer lists, embedding the entire list in an attribute is discouraged.
the <ahref="https://mimesniff.spec.whatwg.org/#image-type-pattern-matching-algorithm">pattern matching algorithm</a>,
3313
3313
due to security implications, and instead recommend enforcing strict MIME types for newer formats.</p>
3314
3314
<p>New MIME types should have a specification and should be registered with the Internet Assigned Numbers Authority (IANA).</p>
3315
-
<h3class="heading settled" data-level="10.5" id="using-http"><spanclass="secno">10.5. </span><spanclass="content">Consult documentation on best practices when using HTTP</span><aclass="self-link" href="#using-http"></a></h3>
3316
-
<p>When using <adata-link-type="biblio" href="#biblio-rfc9110" title="HTTP Semantics">HTTP</a>,
3317
-
consult <adata-biblio-display="inline" data-link-type="biblio" href="https://httpwg.org/specs/rfc9205.html"><cite>Building Protocols with HTTP</cite></a> for advice on correct usage of the protocol.</p>
3318
-
<p><ahref="https://fetch.spec.whatwg.org/">Fetch</a> is the way that
3319
-
user agents most often interact with servers.
3320
-
Fetch defines the CORS protocol and necessary security checks.
3321
-
Outside of those constraints necessary for security,
3322
-
Fetch does not provide guidelines on how to best use HTTP.
3323
-
Appropriate use of methods, header fields, content types, caching, and other HTTP features
3324
-
might need to be defined.</p>
3325
-
<p>Recommendations on best practices for HTTP
3326
-
can be found in <adata-biblio-display="inline" data-link-type="biblio" href="https://httpwg.org/specs/rfc9205.html"><cite>Building Protocols with HTTP</cite></a> and <ahref="https://datatracker.ietf.org/doc/search?name=HTTP&sort=&rfcs=on&by=group&group=httpbis">other HTTP RFCs</a>.
3327
-
RFC 9205 includes advice on <ahref="https://httpwg.org/specs/rfc9205.html#section-4.3">specifying client behavior</a>, <ahref="https://httpwg.org/specs/rfc9205.html#section-4.7">defining header fields</a>, <ahref="https://httpwg.org/specs/rfc9205.html#section-4.8">use of media types</a>, <ahref="https://httpwg.org/specs/rfc9205.html#section-4.16">evolving specifications</a>, and
3328
-
other advice on how to get the most out of HTTP.</p>
3329
-
<h3class="heading settled" data-level="10.6" id="extend-manifests"><spanclass="secno">10.6. </span><spanclass="content">Extend existing manifest files rather than creating new ones</span><aclass="self-link" href="#extend-manifests"></a></h3>
3315
+
<h3class="heading settled" data-level="10.5" id="extend-manifests"><spanclass="secno">10.5. </span><spanclass="content">Extend existing manifest files rather than creating new ones</span><aclass="self-link" href="#extend-manifests"></a></h3>
3330
3316
<p>If your feature requires a manifest,
3331
3317
investigate whether you can extend an existing manifest schema.</p>
3332
3318
<p>New web features should be self-contained and self-describing and ideally should not require an additional manifest file.
<p>Should not add to error accumulation - taking the serialized output of an API and feeding it back to the same API in a loop should result in the same internal state</p>
3395
3381
</ul>
3396
-
<h3class="heading settled" data-level="10.8" id="debuggability"><spanclass="secno">10.8. </span><spanclass="content">Ensure features are developer-friendly</span><aclass="self-link" href="#debuggability"></a></h3>
3382
+
<h3class="heading settled" data-level="10.7" id="debuggability"><spanclass="secno">10.7. </span><spanclass="content">Ensure features are developer-friendly</span><aclass="self-link" href="#debuggability"></a></h3>
3397
3383
<p>Any new feature should be developer-friendly.
3398
3384
While it is hard to quantify friendliness, at least consider the following points.</p>
3399
3385
<p>While error text in exceptions should be generic,
it also ensures a consistent development experience for the users.</p>
3410
3396
<p>A good example where debuggability was defined as
3411
3397
part of the specification is <ahref="https://www.w3.org/TR/web-animations-1/#use-cases">Web Animations</a>.</p>
3412
-
<h3class="heading settled" data-level="10.9" id="crypto"><spanclass="secno">10.9. </span><spanclass="content">Use the best crypto, and expect it to evolve</span><aclass="self-link" href="#crypto"></a></h3>
3398
+
<h3class="heading settled" data-level="10.8" id="crypto"><spanclass="secno">10.8. </span><spanclass="content">Use the best crypto, and expect it to evolve</span><aclass="self-link" href="#crypto"></a></h3>
3413
3399
<p>Use only cryptographic algorithms
3414
3400
that have been impartially reviewed by security experts,
3415
3401
and make sure your choice of algorithm is proven, and up-to-date.
3416
3402
Not only do they become obsolete or insecure,
3417
3403
cryptographic protocols and algorithms also evolve quickly.</p>
3418
-
<h3class="heading settled" data-level="10.10" id="client-hints"><spanclass="secno">10.10. </span><spanclass="content">Do not expose new information through Client Hints</span><aclass="self-link" href="#client-hints"></a></h3>
3404
+
<h3class="heading settled" data-level="10.9" id="client-hints"><spanclass="secno">10.9. </span><spanclass="content">Do not expose new information through Client Hints</span><aclass="self-link" href="#client-hints"></a></h3>
3419
3405
<p>When using Client Hints, don’t expose information that the web page does not already have access to.</p>
3420
3406
<p>Client hints are an important optimization, but cannot be the sole means by which information
3421
3407
is exposed to sites. As it says in <cite><ahref="https://datatracker.ietf.org/doc/html/rfc8942#section-4.1-5">RFC 8942 §4.1</a></cite> where client hints are defined:</p>
"37ef25b8": {"dfnID":"37ef25b8","dfnText":"HTMLHtmlElement","external":true,"refSections":[{"refs":[{"id":"ref-for-htmlhtmlelement"}],"title":"Use casing rules consistent with existing APIs"}],"url":"https://html.spec.whatwg.org/multipage/semantics.html#htmlhtmlelement"},
4902
4893
"3a2db83f": {"dfnID":"3a2db83f","dfnText":"localStorage","external":true,"refSections":[{"refs":[{"id":"79d831630"}],"title":"2.10. Consider how your API should behave in private browsing mode"},{"refs":[{"id":"ref-for-dom-localstorage"}],"title":"10.3. Only purely computational features should be exposed everywhere"}],"url":"https://html.spec.whatwg.org/multipage/webstorage.html#dom-localstorage"},
4903
4894
"3b64181e": {"dfnID":"3b64181e","dfnText":"none","external":true,"refSections":[{"refs":[{"id":"ref-for-valdef-font-size-adjust-none"}],"title":"11.4.1. If you need to monkey patch"}],"url":"https://drafts.csswg.org/css-fonts-5/#valdef-font-size-adjust-none"},
4895
+
"3c05c488": {"dfnID":"3c05c488","dfnText":"Accept","external":true,"refSections":[{"refs":[{"id":"ref-for-name-accept"}],"title":"3.2. Use space-separated attributes for short lists of values, separate elements for longer lists"}],"url":"https://www.rfc-editor.org/rfc/rfc9110.html#name-accept"},
4904
4896
"3da24a47": {"dfnID":"3da24a47","dfnText":"ping","external":true,"refSections":[{"refs":[{"id":"ref-for-ping"}],"title":"3.6. Name URL-containing attributes based on their primary purpose"}],"url":"https://html.spec.whatwg.org/multipage/links.html#ping"},
4905
4897
"3f03fff1": {"dfnID":"3f03fff1","dfnText":"datalist","external":true,"refSections":[{"refs":[{"id":"ref-for-the-datalist-element"}],"title":"3.2. Use space-separated attributes for short lists of values, separate elements for longer lists"}],"url":"https://html.spec.whatwg.org/multipage/form-elements.html#the-datalist-element"},
4906
4898
"3f597ac1": {"dfnID":"3f597ac1","dfnText":"createImageBitmap(image, options)","external":true,"refSections":[{"refs":[{"id":"ref-for-dom-createimagebitmap"}],"title":"6.8. Classes should have constructors when possible"}],"url":"https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#dom-createimagebitmap"},
"fdf6efd5": {"dfnID":"fdf6efd5","dfnText":"font-size","external":true,"refSections":[{"refs":[{"id":"ref-for-propdef-font-size"},{"id":"ref-for-propdef-font-size\u2460"},{"id":"ref-for-propdef-font-size\u2461"}],"title":"4.2. Make appropriate choices for whether CSS properties are inherited"},{"refs":[{"id":"ref-for-propdef-font-size\u2462"},{"id":"ref-for-propdef-font-size\u2463"},{"id":"ref-for-propdef-font-size\u2464"},{"id":"ref-for-propdef-font-size\u2465"},{"id":"ref-for-propdef-font-size\u2466"}],"title":"4.3. Choose the computed value type based on how the property should inherit"}],"url":"https://drafts.csswg.org/css-fonts-4/#propdef-font-size"},
5080
5072
"ff87eaf9": {"dfnID":"ff87eaf9","dfnText":"remove","external":true,"refSections":[{"refs":[{"id":"ref-for-abortsignal-remove"},{"id":"ref-for-abortsignal-remove\u2460"}],"title":"7.6. Guard against potential recursion"}],"url":"https://dom.spec.whatwg.org/#abortsignal-remove"},
"monkey-patch": {"dfnID":"monkey-patch","dfnText":"monkey patch","external":false,"refSections":[{"refs":[{"id":"ref-for-monkey-patch"}],"title":"10.6. Extend existing manifest files rather than creating new ones"},{"refs":[{"id":"ref-for-monkey-patch\u2460"}],"title":"11.4.1. If you need to monkey patch"}],"url":"#monkey-patch"},
5074
+
"monkey-patch": {"dfnID":"monkey-patch","dfnText":"monkey patch","external":false,"refSections":[{"refs":[{"id":"ref-for-monkey-patch"}],"title":"10.5. Extend existing manifest files rather than creating new ones"},{"refs":[{"id":"ref-for-monkey-patch\u2460"}],"title":"11.4.1. If you need to monkey patch"}],"url":"#monkey-patch"},
"https://webidl.spec.whatwg.org/#idl-unsigned-long-long": {"displayText":"unsigned long long","export":true,"for_":[],"level":"1","normative":true,"shortname":"webidl","spec":"webidl","status":"current","text":"unsigned long long","type":"interface","url":"https://webidl.spec.whatwg.org/#idl-unsigned-long-long"},
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments