search

emberjs / guides

This repository is DEPRECATED!
https://github.com/ember-learn/guides-source
Other
282 stars 873 forks source link

Should Mirage be the back end of the tutorial? #1695

Open mike-north opened 8 years ago

mike-north commented 8 years ago

I was just helping some newcomers go through the ember guides, and Mirage seems to be causing some potentially un-needed complexity. It boils down to two reasons:

  1. Developers who have come out of a "vanilla" JavaScript course like FreeCodeCamp have learned to look at their dev tools network tab for XHR debugging. In some cases they feel like they've been robbed of one of their key tools, and I tend to agree with them.
  2. Using mirage, or anything based around Pretender, is different from the way an app will end up consuming data in a "real" situation.

My proposed change (I'm volunteering if there's consensus that this is ok) is to replace mirage with use of http mocks and ember-cli.

I realize that when you end up deploying the app, ember-cli won't end up providing this data, but I propose that we handle that as a separate problem (i.e., providing a read-only "production" API for "guides projects" that anyone can use via heroku or something) in the interest of making things as simple and pure to official ember stuff as possible. Again, I'm volunteering to build said API in the interest of improving learning material for newcomers.

Finally, there's enough complexity involved with using ember and ember-data together straight from the start. Involving another addon leaves newcomers confused as to where the lines between these libraries are, and more importantly, the "usual stuff people use" vs the stuff that's included with the guides for convenience or happenstance.

toddjordan commented 8 years ago

Thanks for raising the issue. Its an interesting one. We'll bring it up for discussion at the next learning team meeting, and we'll update this issue on what we decide (+link to notes on the discussion).

samselikoff commented 8 years ago

Let me know if I can be of help on this issue. We have an issue on the backlog to make Mirage able to serve out of Ember CLI (from node), which would bring back the network tab. The next goal after that is to have Mirage read model definitions from Ember Data, if you happen to be using it.

If we had these features it might make the experience feel more like using Rails with SQLite out of the box. If it feels right I can do some recruitment to get these features in faster.

mike-north commented 8 years ago

I've had seen an increase in success teaching ember (measured by post-workshop survey to measure depth and breadth of understanding) since I rewrote my curriculum to start with the simplest, purest and most basic teachable piece possible (HTML and data binding in application.hbs) first, and then very gradually layering things on.

Ember-data comes much later, and of course mirage would have to come after that (if at all).

The benefit of this approach is that we start with the smallest functional atom of an ember-cli ember app that's possible, and then explain as we introduce new concepts one-by-one.

As things stand now, beginners are left without an understanding of where the lines are between ember, ember-data and mirage, because they're all thrown at the reader at once. It feels very much like someone decided they wanted an example that they could deploy a "server-less" app (the vast majority of apps are not like this), and worked backwards.

samselikoff commented 8 years ago

This makes a lot of sense to me, especially if you consistently see confusion arise during teaching. I've also had to explain that Mirage is not Ember Data many times. It's a lot of abstraction all at the beginning.

toddjordan commented 8 years ago

Thanks for this feedback. Its useful to understand your experience teaching intro workshops and learn what has worked for you.

The reason we included mirage in the tutorial is... 1) Mirage is very frequently used for acceptance testing in ember, (otherwise requiring a data setup/teardown infrastructure). I do think this an important technology to familiarize developers with. 2) We desired to give tutorial followers an application that they could easily run locally without a deployment with server persistence.

We also wanted to follow a workflow that one might start an app with, and have that as a possible pattern for future work, though there are obviously other possible ways to do it that would be as effective.

We did talk about it some last week (will post minutes soon) at our learning meeting and will likely discuss again this week. I think there are some things we can do to more clearly address some of the concerns you mention without completely blowing up the tutorial as is. @locks mentioned contacting you this week to get more info. We'll leave this issue open as we work through ways to address

Thanks

mike-north commented 8 years ago

Looking forward to doing whatever I can to make this more approachable for beginners. I'm not looking to "blow up" the existing guides, but as soon as I started hovering over beginners' shoulders as they started going through the example, the sticking points were very clear. A little simplification (introduce way fewer concepts in early steps) would go a long way.

toddjordan commented 8 years ago

Thanks, so given issue #1708 I propose we track this issue as finding possible alternatives to using Mirage, wether it be using a hosted service or other solution. Possibly also still using mirage but introducing it later in the tutorial with more care.

toddjordan commented 8 years ago

Discussed some in previous ember learn meeting. No set decisions made on a solution yet: https://github.com/emberjs/core-notes/blob/master/docs-team/2016-10/october-13.md#tutorial-back-end

gr0uch commented 8 years ago

It seems that the goal would be to serve JSON API out of the box, right? That would be most congruent with Ember Data's default adapter/serializer, and would be one less thing to think about.

I've been working on an internal project tentatively named ember-cli-fortune, which just adds ember-cli integration with Fortune.js + Fortune JSON API, and it's used in some demo projects. What it does:

The idea is that one can simply set up Ember Data models, install ember-cli-fortune, add some initial data, and be done with it.

It's not released yet, since I've had no time yet to document it and make a website with guides for it, though I don't expect that there will need to be much of a guide since it's expected to be plug and play. The source code isn't even long at all, ~300 LOC, it's mostly glue code between the AST parser Acorn, Pretender, Ember, and Fortune. Without Pretender it would be much less code.

If there is interest I'm open to discuss this as an alternative to HTTP mocks and/or Mirage.

locks commented 8 years ago

@sapeien how is this different to Mirage?

gr0uch commented 8 years ago

Quite a lot:

mike-north commented 8 years ago

Has consideration been given to a hosted solution, or a "one click deploy" back end on something like heroku?

The idea here is it would be a back end that "just works" and is nearly 100% set up for the learner, so that additional server-side complexity/setup (mirage, http mocks, fortune, etc...) doesn't compete with core ember concepts for attention and learning bandwidth.

It would make sense that this would be written in JS so that it's easy for the community to maintain. Maybe fortune would fit well here too?

mike-north commented 8 years ago

Updated the title of the issue to focus the discussion away from http mocks

locks commented 8 years ago

Has consideration been given to a hosted solution, or a "one click deploy" back end on something like heroku?

Yes, you can find it in core-notes.

gr0uch commented 8 years ago

Has consideration been given to a hosted solution, or a "one click deploy" back end on something like heroku?

I have thought about setting up some managed application service for Fortune.js, but I wouldn't have the business skills or money to keep it running.

The idea here is it would be a back end that "just works" and is nearly 100% set up for the learner, so that additional server-side complexity/setup (mirage, http mocks, fortune, etc...) doesn't compete with core ember concepts for attention and learning bandwidth.

Yeah, that would be a goal of ember-cli-fortune to require no effort to use it, and that it just works in the background.

It would make sense that this would be written in JS so that it's easy for the community to maintain. Maybe fortune would fit well here too?

Sure, it's 100% JS. Also, since the ember-cli integration is fairly concise, it wouldn't be too much of a burden.

samselikoff commented 8 years ago

Just want to reiterate that I am 100% on board with whatever's easiest and best for beginners. Let me know if you need anything from me.

mike-north commented 8 years ago

Yes, you can find it in core-notes.

After reading through the whole collection of notes a few times, here's the most meaningful stuff I could find.

I can't really glean from the notes whether we're rehashing a discussion that's been had, or whether a "deploy it yourself to heroku" 100% complete API (in place of having to learn mirage and ember simultaneously) is new territory or not.

locks commented 8 years ago

[tracking comment]

Local:

Hosts:

APIs:

locks commented 8 years ago

I can't really glean from the notes whether we're rehashing a discussion that's been had, or whether a "deploy it yourself to heroku" 100% complete API (in place of having to learn mirage and ember simultaneously) is new territory or not. @mike-north

We did have these discussions, it's probably in Slack logs then :\ I think this is the gist of it:

1) We host

Too expensive.

2) Self-hosted / Local

Instead of having to learn mirage, you have to learn how to setup a whole backend. Plus the account creation for the hosting service.

3) Firebase-style

Needs custom adapter if using with Ember Data. Needs account creation.

4) Public APIs

Rate limiting. One workshop was blacklisted because they were making the calls from the same IP and hadn't remembered to warn the API owner.

mike-north commented 8 years ago

1) We host: Too expensive.

Based on what? I know node doesn't necessarily scale as well as Elixir/Phoenix, but I've been able to workshop with ~300 students concurrently hitting an API at the same time, using heroku's $7/month dynos

2) Self-hosted / Local: Too burdensome

With heroku this boils down to a one-button deploy after account creation. in your app.json it's possible to specify addons (i.e., postgres) and run a postinstall to setup the initial data in the DB. If we're weighing the conceptual burden of managing mirage against creating a heroku account and clicking a button, I'm not sure if there's much of a contest.

3) Firebase-style: Too complicated

Agree, and it also has the disadvantage of not being an overly common use case for managing persisted state in ember apps

4) Public APIs: Too error-prone

Agree. I am often burned by the GitHub API, and the hoops to jump through to get an OAuth token are prohibitively complicated

runspired commented 8 years ago

@mike-north and whomever else cares, I wrote a json-api mock server for ember-data https://github.com/runspired/json-api-mock-server/, and am slowly growing it to support more things (needs fixtures supports, needs documentation on serializer customization because non-json-api payloads are supported so long as you supply a serializer and schema))

runspired commented 8 years ago

I've also been debating setting up a heroku instance running this with some common model scenarios to use as mock data in ember-twiddle

mike-north commented 8 years ago

A refined server that people new to ember can just point to, would reduce the number of simultaneous things they need learn/do during the tutorial quite nicely.

runspired commented 8 years ago

@mike-north not necessarily, if the tutorial has an addon, that addon could mount my project with the required models. Extra advantage is that in the console you get pretty notifications about the request :)

SaladFork commented 8 years ago

I definitely understand some of the pains and appreciate @mike-north sharing how he teaches (wish I had such training when I started!). There may be ways to improve how mirage is introduced/used in the guides and there are definitely pain points (such as debugging flows) but I'd like to throw in a counterexample to the ongoing discussion.

We recently had a developer go through the Guides as her first exposure to Ember.js. After completing them, we were pleasantly surprised to see her not only able to understand the various parts of our production app and be able to contribute, but also able to read and understand and even write her own acceptance tests with the mirage setup we had with no further instruction from any existing developers.

This lined up with @toddjordan's goal of:

1) Mirage is very frequently used for acceptance testing in ember, (otherwise requiring a data setup/teardown infrastructure). I do think this an important technology to familiarize developers with.

mike-north commented 8 years ago

1) Mirage is very frequently used for acceptance testing in ember, (otherwise requiring a data setup/teardown infrastructure).

Do we have any data that indicates how widely-used mirage is, relative to something that's almost ubiquitous (i.e, ember-data)? This doesn't quite jive with what I've seen in the wild (I tend to see more Pretender than Mirage tbh). Maybe other people have hard data that I don't have?

I do think this an important technology to familiarize developers with.

I don't think anyone's saying that mirage is unimportant or not worth familiarizing developers with.

@SaladFork's new developer would likely have had similar success if the learning path had led from "core ember concepts" to a separate learning trail for any relevant addons. She's representative of the group of people who currently make it through the guides in their current form.

My efforts are aimed at broadening our user base, and allowing people like her to continue to have success, while opening the door to others who are currently getting stuck right at the start, before they can even get off the ground.

runspired commented 8 years ago

Regardless of final approach, I think a tutorial addon (supplying data) and baking a standard mock setup into twiddle for use in twiddle's would be amazing for helping beginners / tinkerers / bug reporters

samselikoff commented 8 years ago

@runspired I love this idea, especially for Twiddle. In the event that a hosted solution requires more effort and is a ways out, we could use Mirage to do this today with an addon that (1) includes Mirage as a dependency and (2) predefines several models w/relationships and sets up their endpoints (user, post, comments). We should be able to build that today without much trouble.

toddjordan commented 8 years ago

Do we have any data that indicates how widely-used mirage is, relative to something that's almost ubiquitous (i.e, ember-data)? This doesn't quite jive with what I've seen in the wild (I tend to see more Pretender than Mirage tbh). Maybe other people have hard data that I don't have?

@mike-north If you go by npm downloads and github stars/forks then mirage is more popular than pretender. Its not a real fair comparison though, as they have different jobs, and mirage is actually built using pretender. If you are developing an acceptance testing suite, then mirage has more for you to organize/manage your data. Pretender is great for adhoc testing integration tests (though I'm not saying it can't, shouldn't, or is not used for acceptance).

The ember-data to mirage comparison is also not real fair, since more people probably don't acceptance test than do. While ember data is seen as part of the ember core framework for data access (it comes out of the box with CLI, released on the website, has a core team) You can certainly do acceptance tests without mirage using a real data persistence, or alternative stubbing technologies, but mirage is what I've observed, based on teams, podcasts, literature, downloads, etc as the way a lot of ember teams tend to solve it.

But again, I am not arguing that nothing should be done. I think we can push introducing mirage until further along, and I think it worth looking at solutions for the tutorial that can give users an example of data access without having to learn or mess with new concepts, allowing them to focus on ember-data basics.

toddjordan commented 8 years ago

My efforts are aimed at broadening our user base, and allowing people like her to continue to have success, while opening the door to others who are currently getting stuck right at the start, before they can even get off the ground.

Agree ❤️, and thanks for contributing to this discussion. Its certainly clear that there are different personas using the guides, and providing useful content to both is important.

acorncom commented 8 years ago

@mike-north Regarding your questions from earlier ...

1) We host: Too expensive.

Based on what? I know node doesn't necessarily scale as well as Elixir/Phoenix, but I've been able to workshop with ~300 students concurrently hitting an API at the same time, using heroku's $7/month dynos

Our main issue here has been that the learning team has effectively no budget 😀 So you're right, a Heroku setup for a workshop would be pretty reasonable. But in your case, your students pay the cost of the dyno as part of the workshop fee. Ours don't 😉 Which (if memory serves) was why we skipped it to start with. We might be able to run this on a free Heroku instance though ...

2) Self-hosted / Local: Too burdensome

With heroku this boils down to a one-button deploy after account creation. in your app.json it's possible to specify addons (i.e., postgres) and run a postinstall to setup the initial data in the DB. If we're weighing the conceptual burden of managing mirage against creating a heroku account and clicking a button, I'm not sure if there's much of a contest.

Part of our initial thinking about introducing Mirage was that we wanted to keep from introducing too many moving parts (accounts, add ons, etc). Instead, what we were after was showing how you could fake a data payload in the model hook to start with (while building your initial UI) and then slowly shift it toward a "backend" (with Mirage standing in for the backend). Part of the goal with the model hook faked payload was to expose the fact that the model hook can take any type of data (something that we've heard a lot of folks be confused about if they go straight to using Ember Data there).

Once we got the data into Mirage, I'd envisioned eventually setting up Ember Data as well (and explaining how that worked with Mirage handling the data generation). That would then in turn ease our testing story (as our tutorial-taker already is using Mirage, is somewhat comfortable with it and can build things out as part of TDD).

You can argue (and you have been arguing successfully 😉 ) that we may not have hit the speed right in the tutorial (and the tutorial obviously doesn't yet handle things as slowly or smoothly as what I've outlined above). But would you say the additional steps to setup a new Heroku account (assuming our tutorial-taker doesn't have one yet) are worth the ability to have Ajax responses visible in the Network pane in the short-run if we're aiming for something like the above?

And if @samselikoff wrangles in a Node backend as part of Mirage does that change the calculus?

As far as:

Do we have any data that indicates how widely-used mirage is, relative to something that's almost ubiquitous (i.e, ember-data)? This doesn't quite jive with what I've seen in the wild (I tend to see more Pretender than Mirage tbh). Maybe other people have hard data that I don't have?

As we weighed our options back when we were starting in on the tutorial, the common consensus we were seeing / hearing in the community (and core team members) seemed to indicate the Mirage was what folks were choosing (especially for new apps). In the apps you've seen with Pretender (instead of Mirage), were those older apps (or apps with Ember devs who have been around longer)? But no, I don't think there's any clear, hard data.

I guess another question here is: "by the time a person has shifted from new Ember user to comfortable as a junior Ember dev, what technologies do we as the learning team want to have exposed them to?". Part of the reason we thought it was a good idea to choose Mirage was that it seemed to provide a comprehensive solution to both prototyping an initial app and then building good acceptance tests. As the learning team, we're not just following community thought here but also are aiming to nudge the community toward what we recommend as good practice ... 😀

mike-north commented 8 years ago

But in your case, your students pay the cost of the dyno as part of the workshop fee

I guess, but I have it on a $7/month dyno. We could collect $36 from each of the top 7 ember consultancies as a donation and be set for the next three years :) Frankly I feel like this is not an insurmountable barrier.

Free heroku instances "sleep" for a few hours a day, so they're probably not appropriate for this kind of thing.

Part of our initial thinking about introducing Mirage was that we wanted to keep from introducing too many moving parts (accounts, add ons, etc). Instead, what we were after was showing how you could fake a data payload in the model hook to start with (while building your initial UI) and then slowly shift it toward a "backend" (with Mirage standing in for the backend). Part of the goal with the model hook faked payload was to expose the fact that the model hook can take any type of data (something that we've heard a lot of folks be confused about if they go straight to using Ember Data there).

  • I like (and practice) the concept of starting with JS array/object literals in model, and then moving toward ember-data.
  • Back when active record was the ember-data standard, I liked throwing $.getJSON() in there as well to demonstrate the async thing before dropping ember-data on learners -- it's a little harder with JSON-API

Mirage/pretender may feel natural for some in the ember community, but there are a lot of moving parts that require some portion of the learner's attention and focus. Ember is already incredibly complex (and powerful), so it would stand to reason that we should minimize additional complexity for newcomers wherever possible.

I'm liking the idea of "sign up for an account and deploy your API project to heroku" less and less, since you rightly point out that these are extra steps too. My feeling is that we should aim for a free-standing API that developers can simply point to. Even if this API is read-only (so we don't have to worry about user-generated content), it would allow for a simpler and "more real" path (meaining: more similar to a practial client/server app) than the tutorial takes today. This includes options like:

This have the added benefit of allowing things like DS.Store#query to be added with very little UI-side complexity involved, which might make it easier to feel the benefits of ember-data earlier on!

Maybe "mirage via node" fits this vision -- as long as learners don't have to touch it or think about it, we'll have successfully simplified the first exposure people have to ember.js.

as the learning team, we're not just following community thought here but also are aiming to nudge the community toward what we recommend as good practice ... 😀

I see this and support it, but maybe we need to consider if this needs to take place in the tutorial.

toddjordan commented 7 years ago

Here's a possible order of topics

As a first step we can remove mirage from "Installing Addons" and just do the style addon, and then delay it until Ember Data. When we do introduce we add some text around what is mirage and how is it different from a remote.

Second phase is incorporate a hosted/http solution, but the first can be done for a fairly quick win.

toddjordan commented 7 years ago

I'm going to take a stab at pushing Mirage back to after the "Nested Routes" section, and use Http Mocks up to that point. That way we can still deploy with a client side solution, but we push mirage back to the end, where an inexperienced user can choose to take it on or stop, having gotten through most of the core concepts.

I'll do a PR and elicit feedback on how it flows.

toddjordan commented 7 years ago

Quick update: http-mocks may be being phased out. At the same time there's an effort to create an express-based version of mirage. I'll find out more and come back to this.

mike-north commented 7 years ago

@toddjordan I'm working on a free-standing API for common types of apps that I can train against (i.e., a chat app, an ecommerce app, a CMS, the tiniest social network in the world). Would it be worth exploring whether this is an even simpler way to meet the needs of tutorial consumers?

toddjordan commented 7 years ago

yeah, would be open to it. Thanks!