Explicitly Indicate Versions of Yew, and Yew Packages in Project Examples

[andar1an]

This is about:

• Inaccurate/misleading documentation (e.g. technically incorrect advice)

Problem
All examples such as https://github.com/yewstack/yew/blob/master/examples/router/Cargo.toml do not explicitly state versions of Yew/Yew Packages being used which can lead to confusion due to compile errors, especially as Yew appears to change rapidly.

All examples within Yew follow the same pattern of dependency declaration yew = { path = "../../packages/yew" }, though I think it would be highly valuable to end-users to declare yew dependency release explicitly so that issues that arise due to specific versions of Yew being required are less time-consuming. I personally think yew release number would be best, though if just using yew-router = { git = "https://github.com/yewstack/yew.git" } maybe it would be best to indicate what release in the example README.

Questionaire (Optional)

• I'd like to write this documentation
• I'd like to write this documentation but I'm not sure what's needed
• I don't have time to add this right now, but maybe later

[hamza1311]

I think just looking at the branch should tell you what version of Yew examples is using. Examples on master use master, 0.19 (branch and tag) use 0.19, etc. Is that not clear enough?

[andar1an]

It was not to me, but I will admit I am new to this; which is where I am coming from. Many users like me may be coming from other ecosystems as Rust and Wasm are still not widely adopted; it may be beneficial to be more explicit or descriptive in documentation as one of the hardest parts of being new in this ecosystem is knowing resources available, and understanding what and how to use packages and underlying methods and such as it is all new. One of the troubles that I fell into was following the Yew current documentation, however, the examples seem to apply to Next documentation where the release versions of yew and yew packages are now replaced with git reference. It took me some time to figure out where the discrepancy was, and it wasn't until asking the Rust community and being shown docs.rs and how to check implementations that I was able to determine the issue I was having. Personally, I am used to referencing packages by release, and not by git branch, and I would expect examples to be aligned with a release for clarity as time progresses (I assume as pre-V1, things are highly subject to change from release to release). I was also not aware of your branching practices until your comment above, that is really good to know.

[hamza1311]

We should mention it in the README. A note like this should do:

These examples are for the next release, based off master branch.

See examples for current release, 0.19

This note would be updated/removed when releasing

[andar1an]

Cool, thanks @hamza1311. I will get a PR started

[andar1an]

Permission seems to be denied for me to push local branch to remote branch, do you want to make the update? I was saying something like this in pr:

The examples located here are for the "next" release, based on the master branch.
If an example requires a different version of Yew, it will be indicated in the specific examples' readme.

But I would rather add "next" (specific version number for next version) so that is it not confusing in the future if that makes sense.

[hamza1311]

"next" is master. It's better if you keep that naming as it's what's used everywhere else.

You'll need to push to a fork and then make a PR

[andar1an]

Hey @hamza1311, I am done my vaca and won't likely have time for this any time soon (I have not created PR through fork before). I am going to close this issue for now as I am trying to use Yew to build MVP, and need to focus on trying to learn Yew. I will try to remember to do this once I make progress on my MVP.