search

ewasm / design

Ewasm Design Overview and Specification
Apache License 2.0
1.02k stars 125 forks source link

Remove revision number from top-level README #191

Open lrettig opened 5 years ago

lrettig commented 5 years ago

Nothing in this doc is versioned and it's confusing to lead with this. Let's just version the actual specification docs (https://github.com/ewasm/design/blob/master/contract_interface.md, https://github.com/ewasm/design/blob/master/eth_interface.md, https://github.com/ewasm/design/blob/master/system_contracts.md).

axic commented 5 years ago

I'm not sure I understand. It is versioned and this version in the README is the version number.

axic commented 5 years ago

Last August we've argued that a single version is more readable, hence #146 was merged.

lrettig commented 5 years ago

I'm approaching this from a readability perspective. For someone landing on this page trying to learn about Ewasm, it's confusing that the very first thing they see is a version number. What in this doc specifically (README.md) depends on the version number?

axic commented 5 years ago

Is removing a version number entirely from the repository a good approach? Is that version number line the biggest issue with the README right now?

lrettig commented 5 years ago

The revision number exists in other files: https://github.com/ewasm/design/commit/69b3e41af2975dbe56171417bfeee75f19ae1f64#diff-04c6e90faac2675aa89e2176d2eec7d8. I don't see why it belongs in this file. I'm tackling other README stuff in #192.

axic commented 5 years ago

The revision number exists in other files:

Existed before #146 was merged. The only version is in the README.

lrettig commented 5 years ago

well, that's a problem :)

lrettig commented 5 years ago

Existed before #146 was merged. The only version is in the README.

Sorry I missed this fact originally. I created a separate revision file. @axic is this better?

Honestly, the real issue here is that this repo presently serves two different purposes: containing the spec itself, and containing high-level documentation on Ewasm. Just trying to draw a line and be a bit more explicit about this.