QUEST - reading and editing the Octane Guides preview

[jenweber]

Hello! Thanks in advance for your help! While Octane isn't officially released, and won't be for a while, we are providing a "preview" period where adventurous devs can try it out, and they need guides documentation! A lot of work has already been done, so at this stage, we are looking for people to read the draft of the Octane guides and help us fix errors and fill in the blanks. Can you help us polish things up? Word choice doesn't matter much, so if you see stylistic improvements, please open an issue instead of including them in a PR. However spelling, typo fixes, and and factual accuracy are very important and we would love your help with those.

All work should be done by branching from octane in this repository, and all PRs should be pointed at octane, not master. See #583 for ideas of what to look for, and links to a script that will aggregate code blocks, if that is useful to you. Thank you!!!

If you can help, please comment on this issue to say which page within the guides you can review. In your comment, post a link. When you have a PR, in the description please link to this issue.

List of pages that may need volunteers

(read comments below to see if they are taken)

• "Getting Started", url: 'getting-started'
  • "Quick Start", url: "quick-start", #588 Reading of "Getting Started" and "Services" #590
  • "Installing Ember", url: "index", checked during #588 Reading of "Getting Started" and "Services" #590
  • "Core Concepts", url: "core-concepts" - needs an updated image
• "Anatomy of an App", url: "anatomy-of-an-app"
  • "Overview", url: "index"
• "Templating", url: 'templates'
  • "Templating Basics", url: "handlebars-basics" Review and Octanify the template guides #598
  • "Conditionals", url: "conditionals" Review and Octanify the template guides #598
  • "Displaying a List of Items", url: "displaying-a-list-of-items" Review and Octanify the template guides #598
  • "Displaying the Keys in an Object", url: "displaying-the-keys-in-an-object" Review and Octanify the template guides #598
  • "Binding Element Attributes", url: "binding-element-attributes" Review and Octanify the template guides #598
  • "Actions", url: "actions" Review and Octanify the template guides #598
  • "Built-in Helpers", url: "built-in-helpers" Review and Octanify the template guides #598
  • "Writing Helpers", url: "writing-helpers" Review and Octanify the template guides #598 and Update writing-helpers.md #597
• "Working with JavaScript", url: 'working-with-javascript'
  • "Learning JavaScript", url: "learning-javascript"
  • "Native Classes", url: "native-classes" docs(working-with-javascript): fix minor typos and invalid JavaScript #596
  • "Classic Classes", url: "classic-classes" docs(working-with-javascript): fix minor typos and invalid JavaScript #596
  • "Native vs. Classic Class Cheatsheet", url: "native-vs-classic-class-cheatsheet" docs(working-with-javascript): fix minor typos and invalid JavaScript #596
• "Components", url: 'components'
  • "Component Basics", url: "component-basics"
  • "Defining a Component", url: "defining-a-component" #588 components/defining-a-component #602
  • "Arguments and Attributes", url: "arguments-and-attributes" #588 components/arguments-and-attributes #604
  • "Actions", url: "actions"
  • "Yields", url: "yields"
  • "Interacting with the DOM", url: "interacting-with-the-dom"
  • "Contextual Components", url: "contextual-components"
  • "Classic Components", url: "classsic-components"
• "Routing", url: 'routing'
  • "Introduction", url: "index"
  • "Defining Your Routes", url: "defining-your-routes"
  • "Specifying a Route's Model", url: "specifying-a-routes-model"
  • "Rendering a Template", url: "rendering-a-template"
  • "Redirecting", url: "redirection"
  • "Preventing and Retrying Transitions", url: "preventing-and-retrying-transitions"
    isAdvanced: true
  • "Loading / Error Substates", url: "loading-and-error-substates"
    isAdvanced: true
  • "Query Parameters", url: "query-params"
  • "Asynchronous Routing", url: "asynchronous-routing"
    isAdvanced: true
  • "Controllers", url: 'controllers'
• "State Management", url: 'state-management'
  • "Overview", url: "index" Remove awkward sentence #595
  • "Tracked Properties", url: "tracked-properties" Several updates for clarity/typos. #606
  • "Patterns for State", url: "patterns-for-state" [OCTANE] nitpick: make run loop description consistent #580
  • "Computed Properties", url: "computed-properties"
• "Services", url: 'services'
  • Introduction, url: "services" #588 Reading of "Getting Started" and "Services" #590 and #588 Reading of "Getting Started" and "Services" #590
• 'Data Management', url: 'data-management'
• "Ember Data", url: 'models' (skipping this for now)
  • "Introduction", url: "index" #588 - octane - guides update - model/index #629
  • "Defining Models", url: "defining-models"
  • "Finding Records", url: "finding-records"
  • "Creating, Updating and Deleting", url: "creating-updating-and-deleting-records"
  • "Relationships", url: "relationships"
  • "Pushing Records into the Store", url: "pushing-records-into-the-store"
    isAdvanced: true
  • "Handling Metadata", url: "handling-metadata"
    isAdvanced: true
  • "Customizing Adapters", url: "customizing-adapters" [OCTANE] rewrite text and example to use getters #578 and [OCTANE] use static class fields instead of init logic #577
    isAdvanced: true
  • "Customizing Serializers", url: "customizing-serializers"
    isAdvanced: true
• "Addons and Dependencies", url: "addons-and-dependencies"
  • "Managing Dependencies", url: "managing-dependencies"
• "Testing", url: 'testing'
  • "Introduction", url: "index" Reading/Editing/Octaning “Testing” section #594
  • "Application Tests", url: "acceptance" Reading/Editing/Octaning “Testing” section #594
  • "Testing Basics", url: "unit-testing-basics" Reading/Editing/Octaning “Testing” section #594
  • "Testing Components", url: "testing-components" Reading/Editing/Octaning “Testing” section #594
  • "Testing Helpers", url: "testing-helpers" Reading/Editing/Octaning “Testing” section #594
  • "Testing Controllers", url: "testing-controllers" Reading/Editing/Octaning “Testing” section #594
  • "Testing Routes", url: "testing-routes" Reading/Editing/Octaning “Testing” section #594
  • "Testing Models", url: "testing-models" Reading/Editing/Octaning “Testing” section #594
• "Configuration", url: 'configuring-ember'
  • "Configuring Your App", url: "configuring-your-app" Review "configuring" (part one) #665
  • "Configuring Ember CLI", url: "configuring-ember-cli" Review "configuring" (part one) #665
  • "Handling Deprecations", url: "handling-deprecations" Review "configuring" (part one) #665
  • "Disabling Prototype Extensions", url: "disabling-prototype-extensions"
  • "Specifying the URL Type", url: "specifying-url-type"
  • "Embedding Applications", url: "embedding-applications"
  • "Feature Flags", url: "feature-flags"
    isAdvanced: true
  • "Optional Features", url: "optional-features"
    isAdvanced: true
  • "Build targets", url: "build-targets"
  • "Debugging", url: "debugging"
• "Deploying", url: 'deploying'
  • "Overview", url: "index"
• "Upgrading", url: 'upgrading'
  • "Overview", url: 'index'
  • "Editions", url: 'editions' [OCTANE] add missing import for code example #593 and [OCTANE] nitpick: make run loop description consistent #580
  • "Deprecations", url: 'deprecations'
• "Developer Tools", url: "ember-inspector"
  • "Introduction", url: "index"
  • "Installing the Inspector", url: "installation"
  • "Object Inspector", url: "object-inspector"
  • "The Component Tree", url: "component-tree"
  • "The View Tree", url: "view-tree"
  • "Inspecting Routes", url: "routes"
  • "Data Tab", url: "data"
  • "Tackling Deprecations", url: "deprecations"
  • "Library Info", url: "info"
  • "Debugging Promises", url: "promises"
  • "Inspecting Objects via the Container", url: "container"
  • "Rendering Performance", url: "render-performance"
  • "Troubleshooting", url: "troubleshooting"
• "Contributing to Ember.js", url: 'contributing' Grammatical fixes for "Contributing to Ember.js" #623
  isAdvanced: true
  • "Adding New Features", url: "adding-new-features"
  • "Repositories", url: "repositories"
• "Glossary", url: "glossary"
  • "Web Development", url: "web-development"
• 'Reference', url: 'reference'
  • "Syntax Conversion Guide", url: "syntax-conversion-guide"
  • "Accessibility Guide", url: "accessibility-guide"

[muziejus]

I can do getting started and services, if that's ok?

[jenweber]

Thank you! I updated the list with your work!

[muziejus]

I'll do the testing section next.

[betocantu93]

I can do components section

[mixonic]

I'm going through "templating" right now. We will see if I am on track!

[dennismende]

I will do Data Management and Ember Data till Friday.

[richard-viney]

I'll review the "Working with JavaScript" section.

[kgautreaux]

I have submitted a PR for "tracked-properties" so I can claim that post-hoc.

[mixonic]

I'm also doing a read through components this morning, mostly with an eye toward using actions consistently as described in #598 (comment).

tl;dr is:

• On native class glimmer components, ember components, and controllers use the @action decorator and the element modifier {{action this.actionMethod}} passing the method.
• On classic .extend( ember components and controllers use the actions: { hash and the {{action element modifier {{action 'actionName'}} passing the action name. This usage is no different than best practices today.

[richard-viney]

@mixonic Re. recommended action syntax, I've been a little uncertain on recommended practice of late, as there appears to be no need to use the action helper unless you want to add arguments to the invocation. i.e. you can do @action onClick() {} in the component and then just onclick={{this.onClick}} in the template with no use of the action helper at all. Also if you write {{action this.onClick}} in the template then you don't actually need the @action decorator at all. The latter form does require the this. prefix though.

I wonder if we're effectively double-binding the function by using both the @action decorator as well as the action helper together with this. .. ?

[mixonic]

@richard-viney Please read the comment I linked to above for a more complete description of what we're suggesting for best practice and why. If you still have questions please find me in #st-octane on Discord.

🙏 I'm happy to discuss this topic but lets try to keep comments for this quest issue focused on the work at hand. 🍻

[muziejus]

"Core Concepts", url: "core-concepts" - needs an updated image

I'll make a new image this weekend.

[balinterdi]

I'd like to do the following from the ED section:

• Defining Models", url: "defining-models"
• "Finding Records", url: "finding-records"

[balinterdi]

I just realized these were done by @efx already (as mentioned by @dennismende above). Shouldn't they be checked out?

[mike-north]

I'm going through computed-properties now

[lisaychuang]

I'll be adding comments to issue #633 as I go through the guides, so far I've gone through:

"Getting Started", url: 'getting-started'

• "Quick Start", url: "quick-start"
• "Installing Ember", url: "index"
• "Core Concepts", url: "core-concepts"

"Anatomy of an App", url: "anatomy-of-an-app"

• "Overview", url: "index" (this section is blank)

[jenweber]

Hey team, thanks so much for all your help! We are aiming to freeze the guides tonight, and will pick up work again after the keynote. Please make sure to rebase whatever you are working on, as some big sweeping updates just went in for spellchecks, code block accuracy, etc. I will review and hopefully merge any PRs that are open right now before the end of day.

Y'all are the best and I can't wait to show this off at EmberConf this week ❤️

[jenweber]

@dennismende to answer your questions:

• We are skipping data management for now
• It is unclear whether link-to will be available in angle brackets for the preview, so let's leave as curly braces for now

We got quite a few updates in for the Routing section today - let me know if you have any to add! Thank you!

[mixonic]

Ah, I see we won't land anything tomorrow. I'm going to take on "Configuration", and if I can get that tucked away I'll take another pass at the most important bits even if they already got 👀

[jenweber]

I'm going to keep working to merge existing PRs tomorrow morning, so for those of you who already got your work PR'd, it will make it in :)

If others like @mixonic still have time to jump in & help, reviewing other people's PRs and doing code suggestions for typos is helpful! I'm going to sleep now so I will catch y'all tomorrow. This is all super good and we are in excellent shape!

[jenweber]

Thanks everyone for your help! As of EmberConf 2019, we reached MVP for the Octane Guides 🎉

Anyone who wants to see the outcomes can visit https://emberjs.com/editions/octane for the preview guides. Octane isn't yet in a stable release of Ember - this is a preview - but we are in really good shape for when it's time to ship! And now, more people can try it out and share their feedback. Awesome work, everyone!

[NotGrm]

I just saw a duplicated paragraph in tutorial, here is the PR to fix it https://github.com/ember-learn/super-rentals-tutorial/blob/master/src/chapters/07-reusable-components.md