Spec conventions

[ptomato]

I'd like to get a document started where we can write down items from tc39/ecma262#2236 as they come up. (Personally, I'd find this to be more discoverable than the open issue.)

This document is intentionally mostly empty — I've only added the one convention I recently learned about which made me think a document would be useful, as an example. I'd like to focus on landing this without blocking on a decision about which conventions should be included. I'm happy to start gradually writing about more of the items from tc39/ecma262#2236 once we have this skeleton in place.

[bakkot]

This actually isn't quite the same thing that #2236 is talking about - the example you've put here is about the observable behavior of algorithms, not the way we write them down editorially.

We should of course also write down the conventions we try to follow for observable behavior, though. Just not necessarily in the same place.

[ptomato]

Sure, we can put it somewhere else as long as it is somewhere, although as an author of ECMAScript spec text I would sure love to have one document that I can consult about conventions, without having to think about whether they are observable or not. Basically, "Here's what you need to know for writing spec text that you might not be able to glean from just following the conventions of the surrounding text."

[ljharb]

Looks great to me! Let's have some editors review before landing tho.

[michaelficarra]

Let's have some editors review before landing tho.

This has normative consequences, so it's not really something the editors have any say over.

[ljharb]

@michaelficarra this is just a "conventions" document, so while it has normative consequences (which plenary always needs to approve), the convention itself doesn't.

[michaelficarra]

@ljharb I don't follow. Either way, this doesn't seem to be in any way related to the duties of editor.

[ptomato]

@michaelficarra The way I was thinking about it, the document would contain things that you, as editors, wish people would do consistently, whether those things are observable to JS or not 😄

[ptomato]

@michaelficarra Do you have an alternative idea for where or how these conventions should be collected? If not, I'd like to proceed with this, as a general place to collect conventions that proposal authors and reviewers should be familiar with. If we find that this manner of organizing it causes problems, we can always move it somewhere else in the future.

[mpcsh]

as an author of ECMAScript spec text I would sure love to have one document that I can consult about conventions, without having to think about whether they are observable or not. Basically, "Here's what you need to know for writing spec text that you might not be able to glean from just following the conventions of the surrounding text."

super +1 to this. I don't care where it goes or whether we need consensus to write this down (personally I don't see how this has normative consequences), but I'd very strongly like to see this proceed in some capacity.

[ptomato]

It sounds like this has support from several people and I'd love to move it forward so that we have a place to put these conventions. What is needed to unblock it?

[michaelficarra]

@ptomato That seems like a question you should run by the chairs. Since this would be speaking on the committee's behalf, they may want it to be presented to committee first or even reach consensus.

Also, I would prefer you not mix any mentions of editorial conventions with this convention for normative requirements. The editors plan to document our editorial conventions in the 262 wiki when we get the opportunity to spend some time on it.

[ptomato]

After seeing tc39/proposal-iterator-helpers#265 today, I've rebased this and made it ready to go again.

I'll admit I don't yet understand why having a guide like this needs the intervention of the chairs or is considered speaking on the committee's behalf. tc39/proposal-iterator-helpers#265 suggests that the convention being discussed here is sufficiently part of the committee's mutual understanding, that a proposal not having followed it merits a normative change? A guide like this might have helped that oversight be caught in the review for stage 3.

But, I'd rather not waste time arguing about that — if this needs the chairs to move forward, then are there any chairs who can advise me on what the next steps are?

[michaelficarra]

Ping @tc39/chairs to advise.

@ptomato If you don't hear from the chairs soon, you should just add an agenda item for March. This is what the short timeboxed discussions section is for.

[michaelficarra]

Related: the W3C maintains a document that serves this purpose for them. We may be able to take inspiration from it.

[ctcpip]

NB: I am speaking with my delegate hat on. I have not discussed this with the chair group, and am not speaking on its behalf.

discussed this today with @ptomato and @gibson042:

• we agreed that we don't think the chairs need to be involved in this. in addition to delegates/IEs, it's more relevant and meaningful for spec editors to be involved than chairs.
• we agreed that bringing this to plenary is a fine idea, but merging and evolving this document doesn't need to be gated on plenary/consensus.
• we agreed this should be merged as it has multiple approvals and no change requests.

nonetheless, as guidance from the chair group was sought, I will follow up.

open questions:

• are spec and/or editorial conventions spec-specific? in other words, do we need multiple documents/guides for different specs?
• a distinction was made between spec conventions and editorial conventions. does it not make sense for them to be colocated?

regardless of the answers, ideally, related content would be centralized

[bakkot]

a distinction was made between spec conventions and editorial conventions. does it not make sense for them to be colocated?

"spec conventions" is kind of a broad term. There's (what I consider to be) a very important distinction between conventions about the observable runtime behavior of the language to keep in mind when designing new features, vs editorial conventions to follow when writing spec text which specifies said behavior; personally I am of the opinion that these have basically nothing to do with each other and should not be colocated.

[ctcpip]

can we get approval on this from the 262 editors group?

[bakkot]

@ctcpip No, per my previous comment. If this gets split into "editorial conventions when writing spec text" and "rules we generally follow when deciding on observable behavior", I'd be happy to approve the "editorial conventions" part; approval of the second part is outside of the scope of our role as editors.

[michaelficarra]

@ctcpip It is not appropriate for the editor group to comment on this. See #119 (comment).

[ctcpip]

I understand, thanks for the prompt reply. Given that this document in itself is neither normative nor rigid, is subject to evolve over time, and its intention is to provide guidance rather than to set rules, let me ask the salient question -- do they editors oppose the merging of this PR?

[michaelficarra]

@ctcpip If the empty headings (which are all referring to editorial concepts) are removed and the title is changed from "Conventions when writing specification text" to something like "rules we generally follow when deciding on observable behavior" as @bakkot suggested, I don't see a problem.

With my editor hat off, I would want this run by committee first, even if it is non-binding. But it is within chair discretion, so that is up to you.

[michaelficarra]

@ptomato Do you want to rebase this against the normative conventions document?

[ptomato]

Done.

[michaelficarra]

@ptomato I'd rather not start an editorial conventions document in this repo. The 262 editors have begun documenting our editorial conventions over on the ecma262 wiki. It's still a WIP, but I think it's more appropriate for each spec's editor group to have a lightweight way of documenting and updating their particular conventions. I'd prefer it if you made this just a needs-consensus PR for the normative convention of parameter processing order.

[ptomato]

Hmm. I'm not fond of forcing contributors to discover closely related guides in widely separated places. In particular that wiki page was something I did not even know existed until now, so I don't find it particularly discoverable.

I understand there's no right answer and we're weighting different things in a tradeoff here, and I realize I might not get what I want; that said, I'd prefer to optimize for the convenience of hundreds of (potential) contributors, rather than three editors.

[michaelficarra]

@ptomato I'm objecting to there being 2 different places where a single editor group's editorial conventions are documented. If we think they are more discoverable from here, a link seems to solve that problem.

I'm also objecting to having a single editorial conventions document because our different editor groups have different conventions.

edit: Also, I don't think it's appropriate to have both the editorial convention changes and the normative convention changes in the same PR.

[ptomato]

I'm also objecting to having a single editorial conventions document because our different editor groups have different conventions.

This actually seems like a bigger problem for contributors, that we should solve ASAP.

Also, I don't think it's appropriate to have both the editorial convention changes and the normative convention changes in the same PR.

🤷