search

ember-learn / guides-source

This repository contains the Ember.js Guides
https://guides.emberjs.com/
MIT License
159 stars 491 forks source link

Runloop guides are out of date #148

Open sohara opened 6 years ago

sohara commented 6 years ago

The guides for the runloop (version 3.4) are quite out of date. They refer to things that no longer exist, such as Ember.run.queues (there are still queues but they are no longer accessible on Ember.run and there is an embedded demo app here: https://s3.amazonaws.com/emberjs.com/run-loop-guide/index.html

That demo app uses an extremely old version of Ember (1.3.2+pre.25108e91).

Not sure what to do here, because it seems a sizable portion of the docs on the runloop are no longer applicable. Perhaps we should just remove the misleading information for now?

jenweber commented 5 years ago

@sohara at minimum, our guides should not provide incorrect info, so I agree that we should remove misleading information.

Do you know any more specifics about which parts are incorrect/unavailable now? Thanks!

sohara commented 5 years ago

@jenweber At a minimum parts of the guides that refer to the internals as being publicly available are misleading. E.g. this section: https://github.com/ember-learn/guides-source/blob/master/guides/v3.4.0/applications/run-loop.md#how-does-the-run-loop-work-in-ember It refers to Ember.run.queues being a publicly accessible array of available queues. This used to be the case but it has been made private at some point in the last year.

Overall I'm not sure how useful it is for the guides to delve into the internals, especially when they are no longer public.

The greatest offender is of course the linked toy app for demonstrating the behaviour of the run loop. It's a good illustration of the behaviour, but since it's literally at least 5 years old it's difficult to say how applicable it is today. I think if the guides are to maintain such demo apps the source could should be embedded in the guides repo and pinned to the respective version of Ember, in order to guarantee they are up to date. Additionally they should only employ public API.

My understanding is that the run loop is to become far less prominent in Ember with the transition to a more modern programming model (roughly the one offered by Octane) and greater employment of async/await are expected to reduce the need for application developers to interact with the runloop directly. I think others would be better placed to elaborate on this (e.g. core team members). At some point I wouldn't be surprised if there is no need for a section on the runloop in the guides, but that's a larger question.

Two options I can think of are 1) simply removing the reference to no-longer public API in this section and 2) trying to rewrite the section to ensure that is as informative about the workings of the runloop as it currently is, but without mention of now-private API. The latter would take some more work and I would probably want input from core team members to ensure it accurately accounts for the current state of the runloop and where things are heading.

Sorry for the long-winded response!

jenweber commented 5 years ago

@sohara it is perfect, thank you.

To-dos for anyone who wants to pick up this issue:

gokatz commented 5 years ago

I would love to help with this

sivakumar-kailasam commented 5 years ago

In addition to @jenweber's comments, anyone working on this can get feedback on the content by checking with framework core authors by reaching out via the #dev-ember-js on discord

jenweber commented 5 years ago

Additional possible fixes for the run loop: https://github.com/ember-learn/guides-source/pull/183#issuecomment-426552380