Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Editorial: For CONTRIBUTING.md, add explicit references to patterns we've evolved over time #10392

Merged
merged 16 commits into from
Sep 9, 2024
33 changes: 31 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,14 @@ In between these clear-cut categories, there is some gray area. Please feel free

## Source formatting

### Line wrapping length

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.
domfarolino marked this conversation as resolved.
Show resolved Hide resolved

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
<dd><span>Parse error</span>. Create a new DOCTYPE token. Set its <i data-x="force-quirks
Expand All @@ -60,8 +64,14 @@ is fine and
```
is not.

Using newlines between attributes and inside attribute values that contain whitespace is allowed.
Always wrap after putting the maximum number of characters on a single line within these guidelines.
Using newlines between attributes and inside attribute values that contain whitespace is allowed. Always wrap after putting the maximum number of characters on a single line within these guidelines.

```html
<p>A <code>base</code> element that is the first <code>base</code> element with an <code
data-x="attr-base-href">href</code> content attribute <span>in a document tree</span> has a
```

### Element hierarchy

An `<li>` element always has a `<p>` element inside it, unless it's a child of `<ul class="brief">`.

Expand Down Expand Up @@ -93,3 +103,22 @@ 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).

### Misc wording
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
domfarolino marked this conversation as resolved.
Show resolved Hide resolved

- Use the **"run these steps"** convention to describe what an algorithm that starts with "To", does. [Example #1](https://html.spec.whatwg.org/C#parse-a-url); [Example #2](https://html.spec.whatwg.org/C#create-a-potential-cors-request).
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
- **"If foo, then bar"** instead of "If foo, bar". [Example](https://github.com/whatwg/html/pull/10269#discussion_r1568114777).
- **"Abort these steps" vs "return"**.
- We've passively evolved the pattern of reserving "return" for exiting algorithms and methods, and "abort these steps" for terminating a set of substeps / [in parallel](https://html.spec.whatwg.org/C#in-parallel) steps without messing with the control flow of the "outer" procedure. See [this logic](https://github.com/WICG/portals/pull/138#discussion_r292649287), as well as https://github.com/whatwg/infra/issues/258 and https://github.com/whatwg/infra/pull/255.
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
- **Usage of positional, optional, and named[^1] (i.e., linkable) parameters**. See [this logic](https://docs.google.com/document/d/1yxnzjRDVmAR5CC9GcAyY448lBD0u0E98eUEMHDhx1Dw/edit?disco=AAAAeXYly54) for how to order and refer to these.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ?disco=... link only goes to a comment for people with permission to add comments. (Yay Docs permissions.) I'd argue for inlining all the references-to-discussions into this document.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 on inlining. And figuring out how to state it more generally.

Probably https://infra.spec.whatwg.org/#algorithm-params should be referenced from here. But that doesn't give too much guidance on when to use mandatory vs. named-mandatory vs. optional vs. named-optional.

I'm not sure how strong the guidance should be here, but the doc comment you link to is indeed a reasonable default for people to start from.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at this a little bit more, I'm not even sure that the current version of #navigate is consistent with the guidance in the Google doc (there seem to be no optional non-named/linkable parameters in that algorithm declaration, which honestly just seems for the best).

I've simplified this by linking to the infra link @domenic provided above and specifically calling out the fact that you must use named/linkable optional parameters whenever a callsite wants to pass in a later-positioned optional argument without earlier-positioned ones. I think that's reasonable advice, although I'm not sure it's really a. The alternative would be to just say use named params for all optional params, which I think I would prefer (we have too many algorithms that are impossible to audit the callsite/declaration conformance of, in part due to lack of linkability), but that's a bit heavy-handed so I'm not sure how others feel. WDYT about the current version?

- **Nesting 3+ conditions** in an "if all of the following are true" clause, for readability. [Example](https://github.com/whatwg/html/pull/9778#discussion_r1540615160).
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
- **Conjugating algorithm invocations inline** so they read more naturally in English, instead of more procedurally. [Example](https://github.com/whatwg/html/pull/9778#discussion_r1574075112).


Prefer American English to British English. Examples:
domfarolino marked this conversation as resolved.
Show resolved Hide resolved

- "implement**e**r" instead of "implement**o**r"
- "e.g.," vs "e.g."
- "i.e.," vs "i.e."
domfarolino marked this conversation as resolved.
Show resolved Hide resolved

[^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.
Loading