search

yewstack / yew

Rust / Wasm framework for creating reliable and efficient web applications
https://yew.rs
Apache License 2.0
30.65k stars 1.42k forks source link

Create full feature battery-included tutorial for yew #1384

Closed strasdat closed 3 years ago

strasdat commented 4 years ago

Issuehunt badges

Create full feature battery-included tutorial for yew

Should include:

The tutorial should rely on standard/agreed on tools such as wasm-pack, and web-sys recommended by the Rust / Wasm Working Group. It should use the agreed-on approach to build and serve the app (yarn vs. wasm-pack build/rollup vs. python3 -m http.server 8080). Users should not be confused by different alternatives (web-sys, stdweb) - apart from footnotes etc.

Describe alternatives you've considered Looking forward to comments/feedback from experienced yew developers. I'm happy to adapt this feature request.

Additional context Unclear whether this should be a gradual evolution of the current doc, of a separate tutorial section.

IssueHunt Summary #### [hamza1311 hamza1311](https://issuehunt.io/u/hamza1311) has been rewarded. ### Backers (Total: $500.00) - [strasdat strasdat](https://issuehunt.io/u/strasdat) ($500.00) ### Submitted pull Requests - [#1968 Add tutorial](https://issuehunt.io/r/yewstack/yew/pull/1968) --- ### Tips - Checkout the [Issuehunt explorer](https://issuehunt.io/r/yewstack/yew/) to discover more funded issues. - Need some help from other developers? [Add your repositories](https://issuehunt.io/r/new) on IssueHunt to raise funds.
issuehunt-oss[bot] commented 4 years ago

@strasdat has funded $500.00 to this issue.

codec-abc commented 4 years ago

I am also very interested in a tutorial with Yew. While I think a step by step is good for getting started easily it would be a great value to also insist on the bigger picture. I found my way around the tooling and environment and my project is running I lack the vision on how to map my problem to Yew. So a few design rules about how to split an app into components and use agents would help people like me that lack the experience with similar libraries (React, Elm, etc...)

strasdat commented 4 years ago

@codec-abc

Please feel free to modify my proposal/wording:

Should include:

Fool proof step by step guide to install relevant dependencies. Guide to setup a new yew project (ideally without the need of cloning a repo). Guide how to build the web-app and serve it locally. Guide how to iterate / debug code changes. Introduction to component and html in incremental / interactive fashion. (from hello world towards a more complete app such as TODO list.) The tutorial should rely on standard/agreed on tools such as wasm-pack, and web-sys recommended by the Rust / Wasm Working Group. It should use the agreed-on approach to build and serve the app (yarn vs. wasm-pack build/rollup vs. python3 -m http.server 8080). Users should not be confused by different alternatives (web-sys, stdweb) - apart from footnotes etc.

If we agree, I'm happy to update it in the top post!

@codec-abc interested in earning the bounty yourself :D ??

codec-abc commented 4 years ago

Unfortunately, I cannot earn the bounty, at least not for all the points you cited, because I don't master Yew well enough to do it. What I wanted to say is that IMO the tutorial should be a 2 parts one. The first one should be how to get started (the doc does a good job to explain it already but could be refined) and the second should be how to design and structure a Yew application using Messages, Actors and Nested Components (and maybe others topic if needed). This is the part I currently struggle with. I would say the tutorial should aim for an app more complex than a TODO list. It too simple to use advanced topics and grasp a sense of design. I think that you can add that to your original phrasing if this is Ok for you.

jkelleyrtp commented 4 years ago

Hi, I'd be very happy to take this on. I use Yew a lot, and parts of it has actually crept into my day-job.

Here's how we use Yew:

I'm thinking about making the whole thing in markdown so we can either produce a book.toml or as an addendum to the current Yew gitbook.

jkelleyrtp commented 4 years ago

Here's what I've got so far, with big plans to add in more later. https://www.notion.so/The-Definitive-Yew-User-Guide-0893c8cc101440da9228e4b0be118c39

codec-abc commented 4 years ago

A few days ago I discovered @sheshbabu tutorial for a single page application with Yew. To be honest, it is really good and does a good job at doing something more complex than a simple counter. I especially like that it give a way to design application and split it in smaller part as its evolves. It also gives great insight about state management.

So maybe we can see with the author if its somehow be "part" of the documentation because it is so far one of the best tutorial for Yew.

sheshbabu commented 4 years ago

@codec-abc Thanks for the kind words! ❤️ Let me know how I can help 😊

codec-abc commented 4 years ago

@sheshbabu The mains questions here is will it be okay for you if you work end up in a tutorial? Same for the Yew developers (I think the tutorial would be a great addition but I am not a maintainer so we need to check this with them). Another question would be do you want explicit work attribution (link to the original article, etc..)?

Once these questions sorted, there will be questions about how to include it in the existing documentation. But since both your article and Yew's documentation use Markdown it should be really easy to do. Maybe we will need to split it up in a few parts as Yew's pages are usually not that long.

sheshbabu commented 4 years ago

@codec-abc Sure, I'm okay with it but some parts like FetchService, Agents might require rewriting or rewording. Will wait for the Yew developers' decision 😊

codec-abc commented 4 years ago

@jstarry @siku2 Do you have opinions on this?

siku2 commented 4 years ago

I love the idea of having a more complex tutorial in the documentation! @teymour-aldridge is in charge of the documentation so let's include them in this discussion as well.

Side note: if you're on Discord, we have a dedicated #documentation channel if you wish to discuss this live.

codec-abc commented 4 years ago

I gave a shot at integrating the tutorial here. I tried to stay close to the original material. I mostly changed the introduction and conclusion as well as some of minors changes to fit the documentation style. I also removed small passages that were explained in other pages of the documentation.

I can create a PR before but there is a few things I feel there is a few things worth discussing before:

Most of them, ties down to the tutorial containing references to other "things" controlled by sheshbabu.

  1. The tutorial refers to HTTP requests using the API module pattern which is hosted on @sheshbabu blog.
  2. There are a few references (2 I believe) to the @sheshbabu Github repo.
  3. There is a link to a running app which reference https://rustmart-yew.netlify.app.

The potential problems I see is that if the sheshbabu make some change on its side then the documentation page will be out of sync with the content it is referring too. The other way is also true. For example, if the tutorial keep evolving on its own then the code and the tutorial might become out of sync. So, it might be better to have a fork of the code in the depo which could evolve freely if the tutorial is modified later on. It can also happen for the page explaining HTTP requests using the API module pattern and the netlify app.

Except that I feel there is a passage that some of the Yew team does not necessarily agree with. About state management the tutorial contains:

Notice how there’s a direct link between the components that need this state and the global state.

Unfortunately, Yew doesn’t seem to have a good solution for this. The recommended solution is to use Agents for broadcasting state changes via pubsub. This is something I stay away from as it gets messy fast. I hope in future we see something similar to React’s Context, Redux or Mobx etc.

While having insight about state management I don't know if the phrasing match the documentation style. Also if some disagree with this, we might need to explain this not a universal opinion and some people like to handle state management with a different strategy.

teymour-aldridge commented 4 years ago

One potential short-term solution would be to link to a series of "recommended" but unnofficial tutorials.

I think that the problems around ensuring the two remain in sync aren't huge. We should probably fork a copy of the repo and place it under the yewstack organisation. It shouldn't be too hard to host a copy of the app under yew.rs but for the meantime it would probably be fine to just link to the Netlify site (perhaps via the wayback machine).

I think we should explain in the tutorial that the story around state management in Yew is not yet finished and is evolving. (I think that it's natural that state management in Yew will be different to state management in JS libraries because of the differenence between the two languages).

We don't really have a clear "documentation style" as of yet, but my opinion is that we want it to be pretty easy to understand and narrative in style.

codec-abc commented 4 years ago

So basically I can open a PR with just the change for the state management and leaving the links as they are?

teymour-aldridge commented 4 years ago

I guess we can add it and state that the tutorial is a work in progress (and contributions are welcome, as always).

sharpninja commented 3 years ago

I'm a 25 year veteran of web development. I'm tackling Rust a s pivot in my career. Learning Yew through implementing this seems like a fun challenge. I'll be starting immediately.

quenbyako commented 3 years ago

@sharpninja any progress?)

I've already stocked up popcorn, this is the most expensive issue in the issuehunt, Can't wait for 500 bucks to reach the contributor

🍿🍿🍿🍿🍿🍿🍿

sharpninja commented 3 years ago

I'm going to be working on this over the weekend. Thank you for the detailed requirements.

Edit #1:

rhymu8354 commented 3 years ago

What do you think about video tutorials that walk through the whole process? I've made a few of these in the past, and might like to make one about building a web app in Yew, now that I've just gone through the learning process myself.

ranile commented 3 years ago

There has been no activity on recently the so I will be giving this a shot. Yew has changed so much that the article mentioned above/used in the previous PR is out of date.
I will start by adapting the React or Angular's tutorial, whichever one works best (not a complete copy though). It gives us the benefit of having a starting point based on a good tutorial that has already been used by many other people

Update: I ended up using the Kotlin/React tutorial as the base as it seemed the easiest one to follow/adapt/build upon. I also used function components so this tutorial will be based on the master Yew.

quenbyako commented 3 years ago

 @hamza1311 oh crap, i bought 4 trucks of popcorn and ate only half of one... No one take any reward?

image

ranile commented 3 years ago

@quenbyako what?

quenbyako commented 3 years ago

@hamza1311 this issue cost at least 500 bucks on issuehunt, and this was the most expensive issue in all website, so i thought that some guy who create tutorial will be historical person... *sad noizes*

UPD: uhhh, forget it, someone created 1000$ reward for another issue. Crap, opesource community becomes richer and richer lol

ranile commented 3 years ago

Oh, that is assuming I can get the money. I haven't received it after this PR was merged. Maybe @jstarry can help here

strasdat commented 3 years ago

@jstarry, can you help distributing the funds? I'm not too sure how that works, and I have little insight on the progress. Please let me know if there are any action items from my end...

issuehunt-oss[bot] commented 3 years ago

@jstarry has rewarded $450.00 to @hamza1311. See it on IssueHunt