From 62e086c742732b8e84cb59af6dfe9619230f147f Mon Sep 17 00:00:00 2001 From: Dominic Farolino Date: Sun, 8 Sep 2024 22:27:51 -0400 Subject: [PATCH] Editorial: add more guidance to CONTRIBUTING.md --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 54 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 189f8a6b888..5d1ee8e3704 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,12 +42,21 @@ On the other hand, we want to especially keep: In between these clear-cut categories, there is some gray area. Please feel free to open an issue if you think something is being included that shouldn't be, or is being excluded but should be kept. -## Source formatting +## Style guide -Due to the long legacy of the existing text the guidelines below are not always applied. We do require that you apply the guidelines when making changes, though are happy to provide assistance if this proves to be a blocker to you. +The HTML Standard generally follows style conventions listed in the [Infra Standard](https://infra.spec.whatwg.org) and the [WHATWG style guide](https://whatwg.org/style-guide). Additionally, the HTML Standard follows some specific style conventions not captured by those documents, that we enumerate below. + +Due to the long legacy of the existing text, these guidelines are not always applied. We do require that you apply the guidelines when making changes, though we are happy to provide assistance if this proves to be a blocker to you. + +### Source formatting + + +#### Line wrapping length Use a column width of 100 characters and add newlines where whitespace is used. (Emacs, set `fill-column` to `100`; in Vim, set `textwidth` to `100`; and in Sublime, set `wrap_width` to `100`. Alternatively, wrap the paragraph(s) with your changes with https://domenic.github.io/rewrapper/. Make sure that `column length to rewrap` is set to 100.) +#### Wrapping opportunities + Using newlines between "inline" element tag names and their content is forbidden. (This actually alters the content, by adding spaces.) That is, ```html
Parse error. Create a new DOCTYPE token. Set its href content attribute in a document tree has a +``` + +### Element hierarchy An `
  • ` element always has a `

    ` element inside it, unless it's a child of `

      `. @@ -93,3 +108,38 @@ is not indented, but is. End tags must not be omitted (except where it is consistent to do so) and attribute values must be quoted (use double quotes). + +### Common mistakes around prose style + +Most of the style conventions in this section are covered by Infra or the WHATWG style guide, but the editors often have to correct them in contributions anyway. + + - Use the [algorithm declaration conventions](https://infra.spec.whatwg.org/#algorithm-declaration) in the Infra Standard. + - **"If foo, then bar"** instead of "If foo, bar". [Example](https://github.com/whatwg/html/pull/10269#discussion_r1568114777). + - **"Abort these steps" vs "return"**: Use "return" to exit a whole algorithm or method. Use "abort these steps" to terminate a set of substeps or [in parallel](https://html.spec.whatwg.org/C#in-parallel) steps and continue at the next step in the "outer" procedure. See examples in [this section on parallelism](https://html.spec.whatwg.org/C#parallelism) and elsewhere throughout the spec, as well as https://github.com/whatwg/infra/issues/258. + - **Usage of positional, optional, and named[^1] (i.e., linkable) parameters**. Follow the [algorithm parameter conventions](https://infra.spec.whatwg.org/#algorithm-params) in the Infra Standard. In particular, use named/linkable optional parameters in your algorithm declaration when callsites pass in values for them while omitting earlier-positioned optional parameters. + - When **nesting 3+ conditions** in a list, the style should look like so: + ```html +

    • Foo.

      • + +
    • +

      If (all|any) of the following are true:

      + +
        +

      • condition 1;

        • + +

      • condition 2;

        • + +

      • condition 3; (and|or)

        • + +

      • condition 4,

        • +
      + +

      then…

      +
      • + +

    • Baz.

      • + ``` + - **Conjugate algorithm invocations inline** so they read more naturally in English, instead of more procedurally. For [example](https://github.com/whatwg/html/pull/9778#discussion_r1574075112), use `the result of getting the popcorn` instead of `the result of running get the popcorn`. + - Prefer American English to British English; see the [WHATWG style guide](https://whatwg.org/style-guide). + +[^1]: For example, see parameters like https://html.spec.whatwg.org/C#navigation-referrer-policy, which are named/linkable parameters in an algorithm's declaration.