Make finding pre-proposals easier

[codefromthecrypt]

Right now, reference implementations tend to implement many pre-proposal features. To understand the landscape would be easier if there was a way to inventory them before being merged here.

For example, I think the README here could mention what status the proposals merged are in (ex scheduled for 1.1 or later?). While post-MVP will always be correct, some overview seems fair rigor request.
https://github.com/WebAssembly/spec/tree/main/proposals

Another helpful addition would be to ask people who are implementing pre-proposals in reference implementations to tag the repos in a way they are easier to find. For example, this repo has the word "proposal" but as you can imagine, that tag won't narrow things down that well scoped to all repos in github
https://github.com/WebAssembly/extended-name-section

Instead, you could add an unambiguous tag like "wasm-proposal" and then in the README at https://github.com/WebAssembly/spec/tree/main/proposals mention text like

Proposals here are accepted by the community [link] and will be included in a future WebAssembly draft. There are other proposals, many of which already implemented in reference implementations such as wabt [link]. The easiest way to discover potential features is searching for the tag "wasm-proposal" [link].

[tlively]

Have you seen https://github.com/webassembly/proposals? That's the best place to see all of the proposals and what phase they are at. All proposals that are merged into this repo have reached phase 4, which means that they are finished and will definitely be part of the next released spec.

[codefromthecrypt]

right, the main point is that this is literally the text of the proposals markdown here:

"This directory contains overviews for post-MVP proposals that are included in this repository."

Rather than having people learn one by one, seems what you answered could be in that README right?

[Ms2ger]

Does #1409 help? Notably, https://github.com/WebAssembly/spec/tree/main/proposals does not contain "pre-proposals" or proposals to be included in a "future WebAssembly draft" - they are proposals that are already finished and implemented, and are included in the current WebAssembly specification.

[codefromthecrypt]

#1409 helps for sure. Other points remain, but if you have no plans to address them, you can close this and if someone else gets lost consider re-opening it.

[tlively]

@codefromthecrypt I would be happy to make further improvements to the documentation. Can you reiterate what the remaining points are? It looks like I didn't understand them.

[codefromthecrypt]

So the link to the proposals page helps, but bearing in mind this is the spec, it has a little left I think

• It isn't intuitive that the proposals directory on the spec lacks a description of the merged ones. The text https://github.com/WebAssembly/proposals/blob/main/finished-proposals.md should be moved into the README here or at least copied. The spec repo should have an overview in otherwords

Leveraging GitHub tag search probably means making it consistent, and hopefully specific also

• the GitHub tag "proposal" should be renamed to "wasm-proposal" or something specific enough to find only wasm proposals. After that's the case, a search link could be added here or in worst case here https://github.com/WebAssembly/proposals
• Whether the GitHub tag is "proposal" or "wasm-proposal", all the existing proposals should be tagged. That's not entirely the case now, and probably adding instructions in the proposal guide may make this more consistent.

Knowing who if anyone is implementing anything is helpful (ack this may not end up in this repo)

• It is hard to inventory reference implementations because there is no matrix anywhere. It would seem helpful that when a proposal gets to implementation phase at least one could be mentioned as implementing it. This helps others who are trying to figure out which if any implementors are actually implementing proposals

Thanks for listening!

[codefromthecrypt]

PS by who are implementing, I mean projects like Wabt, Wasm-tools or a browser, and ideally when they are mentioned there is a link to a place in the source code relevant to the feature (directory, tracking issue, etc)

[codefromthecrypt]

finally, it may seem like that https://webassembly.org/roadmap/ exists we are good, and it is good, but it isn't precisely what I mean. The roadmap seems generated which may be good in a "proof in the pudding" way, especially for those participating in that feature-detection thing. However, it isn't complete and for example the significantly very far along wasm-tools repo isn't there. Moreover, it is important to know something more precise than the "engine", especially as an implementor as otherwise it is wildly searching around to see what code is involved or even where it is.

Basically, I think the roadmap is good for end users or marketing checkboxes, but something more could be done for the implementation side and possibly auditing Wasm-tools like which features at which phases they have already implemented could help steer something (if there's desire to)

[rossberg]

@codefromthecrypt

• It isn't intuitive that the proposals directory on the spec lacks a description of the merged ones.

Note that each directory in spec/proposals corresponds to one (merged) proposal, and contains the description of that proposal.

Moreover, there is a section in the Appendix of the spec document itself that summarises all changes and provides references to the originating proposal repos:

https://webassembly.github.io/spec/core/appendix/changes.html

Leveraging GitHub tag search probably means making it consistent, and hopefully specific also

• the GitHub tag "proposal" should be renamed to "wasm-proposal" or something specific enough to find only wasm proposals. After that's the case, a search link could be added here or in worst case here https://github.com/WebAssembly/proposals

The proposal page already has the complete list, so what exactly would a search accomplish in addition?

• Whether the GitHub tag is "proposal" or "wasm-proposal", all the existing proposals should be tagged.

I'm afraid I don't follow. AFAICT, a tag applies to a specific commit/branch inside a repo. What exactly do you suggest tagging, and what would be gained by that?

That said, I wish we had established the convention that every proposal repo is to be named proposal-xyz, for more clarity when browsing the organisation. (We could still rename them, but that's probably gonna cause a lot of friction.)

[Ms2ger]

• Whether the GitHub tag is "proposal" or "wasm-proposal", all the existing proposals should be tagged.

I'm afraid I don't follow. AFAICT, a tag applies to a specific commit/branch inside a repo. What exactly do you suggest tagging, and what would be gained by that?

Does this refer to "topics", like these?

[codefromthecrypt]

yes, by tags I meant topics!

I'll drop the other points in any case as I've failed to convince you that a complete README is useful in addition to the web site. you are welcome to your opinion of the opposite and it may be fine with others also.

[rossberg]

Ah, okay, thanks for the clarification. The topics mechanism did not even exist when we started this org, so we never used it. So to boot, one of the admins would have to go through all the repos in the org and retroactively put topics on them. I suppose you'd have to find a volunteer.

[dtig]

Separate from the issue of how information about proposals is surfaced in the README, We do have a tag for proposals that bring up ~25 proposal repositories. A quick look says that we may be missing a few, but most of the proposal repositories are tagged, and I can volunteer to tag the others that don't already have the tag. I'm not sure I understand the workflow in which the using the tag name wasm-proposal is different from just proposal. (Though as a matter of convenience, it might be useful to have separate wasm-proposal& wasi-proposal to differentiate between the two as we have several.)

[codefromthecrypt]

Thanks for the offer to help and listening @dtig!

The reason I suggested wasm-proprosal is because GitHub topics are global scope not org scope, and it is possible someone has a pre-proposal eg not in the same org.
ex. topic:proposal = https://github.com/search?q=topic%3Aproposal

Conversely, if we want to only identify repos forked into the WebAssembly org or with another tag, that's fine, just make sure the search link is scoped accordingly.
ex. topic:proposal org:webassembly https://github.com/search?q=topic%3Aproposal+org%3Awebassembly
ex. topic:proposal topic:webasssembly https://github.com/search?q=topic%3Aproposal+topic%3Awebassembly

Just it seems easier to use one tag, and that could help identify ecosystem who are experimenting, but don't have admin access to WebAssembly org (pre-proposal). Finally, a single tag is an easier experience vs composite. Even if we split the tag, that's cool because wasm-proposal would be different than wasi anyway. This is a good point and personally I would look at them differently.

Regardless If adding a topic was in the guide, I'd guess more repos would tag when they get to a formal stage. If the guide was read and followed is well out of our control :D