Skip to content

Commit 8d62dd2

Browse files
authored
Meta: update contribution guidelines
These have not kept up with changes to the spec's editorial conventions and build tooling.
1 parent 4dc123a commit 8d62dd2

File tree

1 file changed

+7
-26
lines changed

1 file changed

+7
-26
lines changed

CONTRIBUTING.md

Lines changed: 7 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,21 @@ We label [good first issues](https://github.com/whatwg/streams/labels/good%20fir
66

77
## Spec editorial conventions
88

9-
Wrap lines to 120 columns. (This is not yet consistently followed.)
9+
In general, follow existing practice.
1010

11-
Use two-space indents.
12-
13-
Do not introduce explicit `<p>` tags. (Bikeshed does this automatically.)
11+
Wrap lines to 100 columns.
1412

15-
Use "let" for introducing new local variables. Use "set" for updating existing variables or internal slots.
13+
Use single-space indents.
1614

17-
Mark up definitions [appropriately](https://tabatkins.github.io/bikeshed/#definitions). This is mostly applicable when defining new classes or methods; follow the existing examples in the spec.
15+
Do not introduce explicit `<p>` tags. (Bikeshed does this automatically.)
1816

19-
Mark up abstract operations with `throws` or `nothrow` attributes in their heading tags, according to whether or not they can ever return an abrupt completion.
17+
Mark up definitions [appropriately](https://speced.github.io/bikeshed/#definitions). This is mostly applicable when defining new classes or methods; follow the existing examples in the spec.
2018

21-
Use cross-reference [autolinking](https://tabatkins.github.io/bikeshed/#autolinking) liberally. This generally amounts to writing references to "definitions" as `<a>term</a>`, and writing references to classes or methods as `{{ClassName}}` or `{{ClassName/methodName()}}`.
19+
Use cross-reference [autolinking](https://speced.github.io/bikeshed/#autolinking) liberally. This generally amounts to writing references to "definitions" as `[=term=]`, and writing references to classes or methods as `{{ClassName}}` or `{{ClassName/methodName()}}`.
2220

2321
When writing examples or notes, JavaScript variables and values are enclosed in `<code>` tags, not in `<var>` tags.
2422

25-
Use abstract operations in the following scenarios:
26-
27-
- To factor out shared logic used by multiple public APIs, or by multiple other abstract operations. _Example: ReadableByteStreamControllerEnqueueChunkToQueue_.
28-
- To factor out operations that should be called by other specifications. Other specifications do not require checking of arguments, argument parsing, and other invariants; we assume they use abstract operations appropriately, and so we don't need to enforce correctness by throwing an error if not. Thus we often let the public API enforce invariants before calling to an abstract operation that assumes they hold already. _Example: ReadableStreamDefaultControllerClose_.
23+
Use abstract operations to factor out shared logic used by multiple public APIs, or by multiple other abstract operations.
2924

3025
## Reference implementation style
3126

@@ -38,17 +33,3 @@ Alphabetize imports.
3833
Use single quotes.
3934

4035
Pass ESLint.
41-
42-
## Notes on building the standard
43-
44-
The basics of building the standard are explained in the README. Here are some more details that might be interesting.
45-
46-
Building the standard is a two-step process. First, the majority of the conversion work is done via [Bikeshed](https://github.com/tabatkins/bikeshed). Second, we run a custom portion of the [Ecmarkup](https://github.com/bterlson/ecmarkup) pipeline to convert the algorithms from [Ecmarkdown](https://github.com/domenic/ecmarkdown) syntax into HTML, and to automatically add cross-references. This second step requires a recent version of [Node.js](https://nodejs.org/en/) to be installed, and running `npm install` to install the Ecmarkup/Ecmarkdown tools.
47-
48-
If you have Bikeshed [installed locally](https://tabatkins.github.io/bikeshed/#installing), we have a special script to continuously build the standard. Doing
49-
50-
```
51-
npm run local-watch
52-
```
53-
54-
will start a watcher on `index.bs` that will update `index.html` as you edit.

0 commit comments

Comments
 (0)