search

WebAssembly / spec

WebAssembly specification, reference interpreter, and test suite.
https://webassembly.github.io/spec/
Other
3.13k stars 445 forks source link

Wording of README in proposals directory is misleading. #1744

Open fgmccabe opened 5 months ago

fgmccabe commented 5 months ago

It speaks about obsolete proposals. However, this directory is also where proposal authors develop their own proposals .. which are definitely not obsolete.

IMO, this is a side-effect of the whole 'fork the main repo' approach to developing proposals.

tlively commented 5 months ago

Do you mean that proposals/README.md doesn't make sense when it's a sibling of proposals/my-active-proposal in the my-active-proposal repo? The version specifically in the spec repo seems fine as long as its scope is considered to be limited to the upstream spec repo.

fgmccabe commented 5 months ago

That is right.

tlively commented 5 months ago

I'm not sure there's much we can do about this short of changing the proposal workflow to not involve forking the spec.

On the one hand, proposal authors can certainly change this file to say that their proposal is not obsolete, but on the other hand that would probably cause more trouble than it's worth when merging the finished proposal back into the spec.

In practice I'm not sure this is much of an issue because top-level proposal READMEs often link directly to the relevant Overview.md. I'm not sure I've ever even looked at proposals/README.md before this 😅

rossberg commented 5 months ago

Nothing prevents a proposal champion from modifying this file in their fork, as long as they undo that in the final merge PR. Hence I'm with @tlively, I don't think there is a problem here, nor is it actionable.

fgmccabe commented 5 months ago

A follow-up: wht happens to all these explainers once a proposal is merged?

tlively commented 5 months ago

The proposal directories are merged in unchanged and the overviews become historical documents. For example the multivalue explainer is here: https://github.com/WebAssembly/spec/blob/main/proposals/multi-value/Overview.md. These historical explainers are what this README is referring to.