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

Stage 1 proposals should be included in the README #489

Open
gibson042 opened this issue Oct 24, 2023 · 20 comments
Open

Stage 1 proposals should be included in the README #489

gibson042 opened this issue Oct 24, 2023 · 20 comments

Comments

@gibson042
Copy link
Contributor

gibson042 commented Oct 24, 2023

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 whatwg/html#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
Copy link
Member

ljharb commented Oct 24, 2023

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

@gibson042
Copy link
Contributor Author

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
Copy link
Member

ljharb commented Oct 24, 2023

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

@bakkot
Copy link
Contributor

bakkot commented Oct 24, 2023

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
Copy link
Contributor Author

gibson042 commented Oct 24, 2023

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.
  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
Copy link
Member

ljharb commented Oct 24, 2023

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
Copy link
Contributor Author

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
Copy link
Member

ljharb commented Oct 24, 2023

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
Copy link
Member

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
Copy link
Contributor Author

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
Copy link
Member

ljharb commented Oct 25, 2023

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
Copy link
Member

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
Copy link
Member

ctcpip commented Oct 25, 2023

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
Copy link
Contributor

bakkot commented Oct 25, 2023

@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
Copy link
Member

ctcpip commented Oct 25, 2023

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
Copy link
Member

ljharb commented Oct 25, 2023

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
Copy link
Member

ctcpip commented Oct 25, 2023

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:

Screenshot 2023-10-25 at 5 24 44 PM

@ljharb
Copy link
Member

ljharb commented Oct 25, 2023

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
Copy link
Member

ctcpip commented Oct 25, 2023

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
Copy link
Member

ljharb commented Oct 25, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants