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

Codify semantic line breaks as editorial convention #2127

Merged
merged 1 commit into from
Sep 11, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,51 @@ contributors in the pull request's body or in subsequent comments.

If you are making a pull request on behalf of someone else but you had no part in designing the
feature, you can remove yourself with the above syntax.


## Editorial conventions

When editing the spec, please follow these editorial conventions.


### Text macros

Where appropriate, use the
[text macros defined near the beginning of the document](https://github.com/w3c/webauthn/blob/93193a1dcfddf6a6daa4726fafa4f556bff203ca/index.bs#L51-L60).
For example, use `[TRUE]` to render `<code>true</code>`
and use `[=[RP]=]` to render a linked reference to the term "Relying Party".


### Semantic line breaks

Use [semantic line breaks][sembr].
To summarize, this means adding line breaks at semantically meaningful points,
such as after punctuation, before subordinate clauses, etc.
This makes changes easier to review and helps automatic conflict resolution,
as small changes are more likely to affect only one or a few lines
rather than an entire paragraph.
For more examples and rationale, see: https://github.com/w3c/webauthn/issues/2045.

Use semantic line breaks along these additional guidelines:

- Do not change existing text just for the sake of introducing semantic line breaks.
- When changing text that is not formatted with semantic line breaks,
reformat changing lines to use semantic line breaks.
Do not reformat unchanged neighboring lines to use semantic line breaks unless it's very few lines,
or it otherwise helps readability,
or it otherwise seems like a good idea.
- When changing text that already uses semantic line breaks,
add and remove semantic line breaks as appropriate but only as needed for the change.
Do not break or join lines that would otherwise remain unchanged.
- When adding new text, use semantic line breaks.
- Take the [Semantic Line Breaks specification][sembr] as a set of guidelines, not a rigid set of rules.
If a contributor proposes changes that clearly do not use semantic line breaks,
inform or remind them of the convention and ask them to reformat,
but respect their choice of where to place line breaks and do not "bikeshed" the details.
The goal is to make the text easier to work with, not to enforce a style.
- We do not set a hard line length limit, because of how much indentation and markup syntax we use.
As a rule of thumb, aim for about 100 characters per line,
or about 80 characters excluding indentation.
Use good judgement of where to draw the line in each case.

[sembr]: https://sembr.org/