Stage 1 proposals should be included in the README

[gibson042]

The committee is interested in spending time exploring solutions to Stage 1 proposals, so I think they should be included in https://github.com/tc39/proposals#readme for discovery by \<modifier+F> searching. I think they're currently in a separate file to avoid visual clutter, but that can be addressed by putting them in a default-collapsed <details> (whose skipped contents are accessible to find-in-page as of https://github.com/whatwg/html/pull/6466 ), e.g.:

### Stage 3 | Proposal | Author | Champion | _{Test262 Feature Flag} | _{Last Presented} | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- | | … | ### Stage 2 | Proposal | Author | Champion | _{Last Presented} | | ------------------------------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | … |

### Stage 1

| Proposal | Author | Champion | _{Last Presented} | | ------------------------------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | searchMe1 |

or

### Stage 3 Stage 3 proposals are complete solutions awaiting implementation experience, significant usage and external feedback. | Proposal | Author | Champion | _{Test262 Feature Flag} | _{Last Presented} | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- | | … | ### Stage 2 Stage 2 indicates that the committee expects these features to be developed and eventually included in the standard. | Proposal | Author | Champion | _{Last Presented} | | ------------------------------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | … | ### Stage 1 Stage 1 proposals represent problems that the committee is interested in spending time exploring solutions to.

| Proposal | Author | Champion | _{Last Presented} | | ------------------------------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | searchMe11 |

[ljharb]

This was explicitly requested by some delegates and was done in 2019 - #206.

[gibson042]

Right, and I think both of the stated goals ("avoid overwhelming people with the primary list in the readme" and "make a clearer separation between stage 2/3 proposals, and stage 0/1 proposals") would still be satisfied by including Stage 1 proposals as initially-hidden, with the added benefit of making them more discoverable (cf. #488, which prompted this).

[ljharb]

I'm not sure how "click details, modifier key + f" is less typing than "hit /"?

[bakkot]

In at least some browsers (e.g. Chrome) you don't have to click details; find on page works within details elements. So you go to the page with proposals and search for the thing you want, and then you find it even if it's stage 1 with no additional work.

[gibson042]

hit /

That masks a number of steps; it's actually

1. Hit / (or on mobile, scroll up and tap 🔍︎).
2. If certain of [part of] the proposal name, then
   1. Type it in and hit Enter.
   2. Scan through results.
   3. If Markdown source view is insufficient and/or inconvenient for the intended workflow, then
      1. Click on the file.
      2. Click Preview.
      3. Hit \<modifier+F> to find the relevant row.
      4. …
3. Else,
   1. Type "stage" or similar (guessing/remembering the file name "stage-1-proposals.md").
   2. Arrow to "stage-1-proposals.md" and hit Enter.
   3. Hit \<modifier+F>.
   4. Search until the proposal is found.

click details, modifier key + f

Clicking details isn't even necessary in browsers that have implemented https://html.spec.whatwg.org/multipage/interaction.html#interaction-with-details-and-hidden=until-found ; you can just start with \<modifier+F> to find content in a collapsed <details>.

[ljharb]

I would assume someone is either searching for a specific proposal, or through a specific stage, and if the latter, you'd need to know there's separate lists regardless because of the stage 0 list (and the finished and inactive lists).

[gibson042]

It makes sense to limit the README to active proposals, but a stage 1 proposal that has not been abandoned or withdrawn is active—the committee have made an explicit decision to accept and start tracking it. Splitting stage 1 off into a second file avoids clutter, but does so at an unnecessarily high cost in usability. Especially as the committee become more comfortable with bidirectional movement across stages, we should recognize that stage 1 has more in common with stage 2 than it does with stage 0 and present things accordingly.

[ljharb]

The repo's purpose isn't discoverability, it's tracking status, so I'm really not sure there's as much of a usability hit here as you're implying.

[littledan]

Yeah the goal was to highlight focus on projects that the committee expects to make it into the language eventually. Anyway, as one of the requesters of the split, I'm fine with this being regrouped if people prefer another way.

[gibson042]

The repo's purpose isn't discoverability, it's tracking status, so I'm really not sure there's as much of a usability hit here as you're implying.

I'm doubly surprised to see this—first because proposal repositories theirselves tend to be more responsive about updating status than this repository, and second because it's actually so well-suited to that purpose (and in particular better than e.g. the filtering at https://github.com/tc39 when the precise name is not known).

[ljharb]

The first thing is simply false; with very very few exceptions (the one you caught being one) I update this repo during the meeting for years in real time with advancements, and proposal repos often lag months behind.

[michaelficarra]

I would prefer we leave stage 1 proposals off the main page. I don't want to give them more visibility or credibility than they deserve. Often, whether intentionally or not, stage 1 proposal repos contain "worked" examples that may mislead the public into thinking that specific design decisions have already been made, when by definition stage 1 proposals are just trying to communicate a problem.

[ctcpip]

In at least some browsers (e.g. Chrome) you don't have to click details; find on page works within details elements. So you go to the page with proposals and search for the thing you want, and then you find it even if it's stage 1 with no additional work.

@bakkot this isn't working for me in Chrome... I edited the OP examples to include searchMe1 and searchMe11 and Chrome is returning no results while the <details> are not open. what am I doing wrong?

[bakkot]

@ctcpip Dunno, seems like something is weird about this particular document. Try document.write('<details>foobar</details>') in the console and then C-f for foobar.

[ctcpip]

The repo's purpose isn't discoverability

that may not be its purpose in terms of the original intent, but that's certainly one of its functions, and an important one. the TC39 website links here to See proposals in all stages, which is certainly for discovery (as well as status). and it's the only concise, accurate system of record for proposals. searching for proposal repos at the org level is the only viable alternative and that's far from ideal.

[ljharb]

Why would it be at the org level? You can search from the repo page only within the repo, which i think is the default scope.

[ctcpip]

I think we're getting wires crossed here because I don't understand what you're saying. what I meant is that if I am looking for tc39 proposals, the alternative to coming to this repo is searching the tc39 org:

[ljharb]

oh sure! I see the value of the proposals repo in that way.

I'm just saying that once here, "find in page" isn't a particularly effective or important mechanism to find the proposal you're looking for.

[ctcpip]

I would support going farther and putting all the proposals on the same page, details be damned. I find it annoying to have to navigate and would prefer everything to be in one place. it's still organized by stage with headers, working anchors, there's a table of contents, it's not a mahoosive list, etc. I don't really buy the original argument that a well-organized (and not particularly large) document is overwhelming or that the stages are somehow ambiguous in any way.

[ljharb]

I'm not sure what to tell you - it used to be one single document, and it was quite overwhelming for a number of us when we had a fraction of the current number of proposals. If we went back to that now, it would be much more so.