Guides rewrite to use Ember CLI

[joostdevries]

Each of these needs updating to ember-cli style, include new file location feature from #35. Please comment out JSBins (since they're all broken anyway, and we need a new solution):

• [x] application @trek - #51
• [x] components @nicolechung - #18
• [x] concepts @trek #60
• [x] configuring-ember @trek #52
• [x] contributing @stevekinney #69
• [x] controllers @joostdevries - #11
• [x] cookbook @nicolechung - #25
• [x] deprecations removed from guides
• [x] enumerables (no changes required)
• [x] getting-ember @locks - #65 / @bsclifton - #75
• [x] getting-started removed for now
• [x] models @locks - #8
• [x] object-model @joostdevries - #19
• [x] routing @stevekinney - #14
• [x] templates @mikepmunroe #71
• [x] testing @Serabe https://github.com/emberjs/guides/pull/61
• [x] understanding-ember @trek #62
• [x] understanding-ember-data @locks #64
• [x] views @trek #56

[mikepmunroe]

I'll take templates for now.

[bsclifton]

Awesome! Thanks for putting this together :)

[nicolechung]

I'd like to take components, but I'm looking at it and not sure how to tackle the JSbins.

For the index page, I started breaking it out into code snippets:

app/templates/index.hbs
{{#each}}
    {{#blog-post title=title}}
      {{body}}
    {{/blog-post}}
{{/each}}

// app/components/blog-post.hbs --> name must have a dash
<article class="blog-post">
    <h1>{{title}}</h1>
    <p>{{yield}}</p>
    <p>Edit title: {{input type="text" value=title}}</p>
</article>

But further along, the JSbins are used to see how everything fits together step-by-step ('passing-properties-to-a-component/'). Any suggestions?

Also, is there going to be a "components" section and then another section for "addons"?

[joostdevries]

@nicolechung There's a POC of a Ember CLI jsbin by @stefanpenner at http://jsbin.com/zonuhofufo/1/edit?html,output

[nicolechung]

@joostdevries thank you I will use that.

[alexspeller]

I can do some of these, any preference for ones for me to work on?

[locks]

@alexspeller I've heard the tutorial is getting replaced, so probably pick anything but.

[alexspeller]

OK I'll go with "concepts"

[grapho]

I'm interested in contributing, probably in ember-data, anywhere in particular to start?

[alexspeller]

Also, I think that the "views" section should be deprecated and the relevant parts moved to the components section. Maybe that's too much to do right now but using views as specified in the guides is basically wrong at the moment, AFAIK (cc @nicolechung)

[locks]

That's a thought @alexspeller. I'm not sure I'm going to make to this week's meeting, but maybe you can raise up how to coordinate that aspect. My first pass is converting code samples, then checking for deprecations, then if any restructuring needs to happen.

[nicolechung]

I can start with the cookbook, but its rather large. Perhaps we can break it into sections?

[stevekinney]

That sounds like a good idea.

On Fri, Feb 27, 2015 at 6:20 AM, nicole chung notifications@github.com wrote:

I can start with the cookbooks, but its rather large. Perhaps we can break it into sections?

Reply to this email directly or view it on GitHub: https://github.com/emberjs/guides/issues/9#issuecomment-76393055

[nicolechung]

Actually I'm about halfway through the cookbook section, but with questions.

It seems like there are a lot of unlinked cookbook entries. For example, the "User Interface and Interaction" section has 10 entries, but only 7 are linked. I am assuming that those are "unpublished" or unreviewed entries?

I have omitted updating those for now.

Also, it appears that the TOC has a bug, when you flip between using the side navigation and the prev/next buttons within the guide, the links become broken. I've filed an issue [https://github.com/emberjs/guides/issues/20] for it.

[nicolechung]

@joostdevries I submitted a PR for the cookbook https://github.com/emberjs/guides/pull/25

[joostdevries]

@nicolechung @bsclifton @alexspeller @locks @mikepmunroe @stevekinney Please checkout #30, you'll probably need to update code blocks in your section to follow this new convention

[kimroen]

I've looked over the enumerables section, and there is nothing there that would be different with Ember CLI, unless we want to use ES6-syntax for relevant bits. I'm assuming that might be outside the scope for this rewrite.

[pjmorse]

I've noticed all the testing JSBins are broken, will those be fixed under this effort or should I open a separate issue?

[trek]

Please comment out (or remove) JSBins for now. We need a way to express running code modularly.

[Serabe]

I'd like to help. I can start with the testing section if you want me to.

[trek]

@Serabe I've marked you for testing. Please try to get a PR in within a few days so as not block progress.

[trek]

@alexspeller I don't see a PR so I've removed you from concepts to unblock it for someone else.

[alexspeller]

@trek didn't realize I was blocking, I have been away after emberconf and just got back at the end of last week. Planning to finish up in the next few days, I can still do that if you prefer, or would someone else be working on it sooner?

[trek]

@alexspeller it's been claimed.

[alexspeller]

@trek where I got to was:

1. concepts/core-concepts.md and concepts/understanding-web-apps.md don't seem to need updates
2. concepts/naming-conventions.md needs the most updates, quite a lot of stuff there. I got a little bit through that but probably not worth opening a PR for with the little I did
3. concepts/what-is-ember-js.md needs a few code sample updates

[nicolechung]

do we leave out importing Ember?

import Ember from 'ember'

[trek]

@nicolechung yes please. importing will be implied until the framework isn't one giant object bag.

[locks]

@trek @nicolechung does the same go for import DS from 'ember-data';?

[rwjblue]

@locks - yes

[locks]

@joostdevries I've also taken understanding-ember-data https://github.com/emberjs/guides/pull/64

[locks]

@joostdevries and getting-ember https://github.com/emberjs/guides/pull/65

[joostdevries]

@tomdale fyi - this contains an rough overview of the current efforts/status

[mikepmunroe]

Just held the weeky vid call. Myself and @locks were in attendance. @tomdale would love to try to get these PRs into the next versioned API build that occuring tomorrow.

Would be great if everyone could take a peak at their PRs and see if they can get them ready for review, if not already.

@locks is going to grab contributing and deprecations, but it sounds like deprecations doesn't really need much work. That needs to be confirmed though.

Myself and @locks will be on IRC later if you need to reach out for help.

[joostdevries]

Missed the meeting, sorry guys. I've got a big part of tomorrow blocked for Ember stuff. I'll review + update PR's then.

[joostdevries]

@trek do you know what should happen with the tutorial? I've removed @bsclifton / #7 from it as it is more related to "Getting Ember" than "Getting started"

[trek]

@joostdevries We've removed the getting started guide. There was work on a new application for the GSG, but it appears to have stalled.

[stevekinney]

@trek If it's truly stalled, I wouldn't mind picking up that thread.

[joostdevries]

Sorry, should have checked the source first. My suggestion would be to use the "Installing Ember" section from #7 in/as the "Getting Ember" section.

[bsclifton]

The new GSG https://github.com/poteto/ember-getting-started

Looks like there's still great progress being made; I was initially going to break the work that @poteto and @catkins did into discrete steps that a user could follow along with, which could live in the Getting Started section that I made in #7. The project seemed to halt for a while, I know folks had to prep for EmberConf. So the steps never got transcribed and from a documentation point of view, nothing regarding that project was delivered

Great job with all the work on this issue folks :smile: @trek, I should be able to pick up work next week; I'm thinking I'll grab the issues RE: swiftype middleman plugin + extracting the TOC helpers

[stevekinney]

I'm just opened PR #68 to update the deprecations section. @locks and I are still discussing the best way to word L96, but it could theoretically be merged as is.

[stevekinney]

I also just took care of the contributions section with #69.

[locks]

69 is merged.

[mikepmunroe]

@joostdevries templates PR is #71 now, not #24

[joostdevries]

@trek @rwjblue

importing will be implied until the framework isn't one giant object bag.

FYI: https://github.com/ember-cli/ember-cli/pull/3577

[Serabe]

I'm almost finished with my section. There are some minor details waiting for an answer in the PR, but after that it will be ready to be merged @trek @rwjblue

[locks]

https://github.com/emberjs/guides/pull/7 is now https://github.com/emberjs/guides/pull/75

[Serabe]

Seems that all parts are either already rewritten or removed. I don't know what is keeping this issue open, but if I can do anything to help, let me know.

[stefanpenner]

I strongly believe we should enforce import Ember from 'ember' and import DS from 'ember-data' and demonstrate this in the guides. I do not want to take this step backwards https://github.com/ember-cli/ember-cli/pull/3577

[trek]

@stefanpenner but why? This adds a line to the top of every single example and does what? What about code examples that appear in the middle of a hypothetical larger code block? do we show an entire block of code unrelated to the point the guide is trying to make just so we have a place to show import?

There was already discussion around excluding code snippets that aren't relevant to the surrounding text. If you can make a solid case for reversing this, we can try to get it slated for the 1.12 or 1.13 docs.

[trek]

Thanks everyone! <3