My first is ember-cli.
https://ca.non.co.il/index.php/ember-cli-is-making-you-stupid/
This is intended to get a discusion going so wait with the tar and feathers. I’ll really aprechiate some constructive comments and probably some points to what I’m missing. As much as I tried to find info online I could find any explanation on how ember-cli does it magic.
As a developer you shouldn’t use ember-cli unless you actually know how to run most of the build steps manually
I find it pretty irresponsible that developers don’t understand and can (if needed0 implement every layer of abstraction there work rests on.
I mean, can you honestly feel like a professional if you don’t know the potential voltage between two transistors while your program adds two numbers? Or even at a high level, what machine code V8/JSC/SpiderMonkey/Chakra spit out on a given platform for that function you just wrote?
It seems pretty insane to rest on abstractions…
It doesn’t seem like any one bothered to explain that.
Nor does the manual of your new MacBook explain to you the details of system boot. And I suspect you are fine with that.
If you want the information the source is available. I recommend starting at the executable → https://github.com/stefanpenner/ember-cli/blob/master/bin/ember and following the paths.
We have had ~129 brave souls venture into the bowls of ember-cli and return with successful contributions. It would be great to increase this number.
Of course It would be nice if more of these details where in literature. There is an ongoing effort to maintain https://github.com/stefanpenner/ember-cli/blob/master/ARCHITECTURE.md but time isn’t always on our side. Maybe you are the one to help improve it today!
(eval’d) This code is intended to be used in production -
incorrect, when you build a production build of your application there are no eval statements. This is merely a short term development nice-thing to enable file level source maps until we migrate to the new es6-transpiler.
ember build --env production # then inspect the output in dist/
see: https://github.com/stefanpenner/ember-cli/blob/master/lib/broccoli/ember-app.js#L76
Ember community should reverse this process and aspire running development code with almost no build process at all.
Fun Fact, not only is this possible but this is how many ember applications where built for quite literally years. Lessons learned from this lead to the need for modules, build steps and finally ember-cli.
Now no longer does each team need to re-invent the wheel they can instead collaborate with a community, share the burden and fix each others problems. In addition this abstraction has also enabled a whole new and easy way to share add ons between any ember-cli app.
Ember Cli is making you stupid
Ember CLI makes you smart
There is clearly a cost to abstraction learning and this cost is only amplified by mis-aligned or leaky abstractions. As this project matures (and as we have proven already) we constantly remove these leaks. So whats the value in these abstractions? We as a community can do the right thing, we can learn and improve, we can fix incorrect assumptions and the next time you upgrade your apps you will benefit from this team effort without needing to invest the time yourself.
This is the value of software.
Example:
Do you implement CSP in your app? You should, it mitigates a whole category of XSS attacks. But guess what, we are all developers that have real deadlines and we can’t just stop ever time we have a good idea, we would likely never ship anything.
So wouldn’t it be nice if one or two community members could invest the time, and the rest of us just “Get it” when we upgrade? With ember-cli this is in-fact the case and thanks to @rwjblue → Use the content security policy addon for new applications. by rwjblue · Pull Request #2065 · ember-cli/ember-cli · GitHub the next version of ember-cli will transition everyones to be CSP compatible.
Hi Stefan. I really appreciate you took the time to comment. let me first say I think we agree on 90% of the things.
I think ember-cli is a great tool but its documentation is lacking. it seems like most of the documentation effort, is going toward basic use instead of understanding the concept. I guess no one will use ember clii if it wasn’t clear how to run it so of course the documentation has to explain that. But Ember users are developers and they should have a clear path to research farther if they want to.
It would be highly beneficial if there was a readme file intended to explain the structure of ember-cli and how it runs it tasks so it would be easier to explore the code ( as I said maybe this document is already exist and I just failed to find it).
The CSP addon is a great example.
Since you shouldn’t use emebr-cli server in production CSP. setting CSP headers by ember-cli has no real meaning. its only importance is that emebr-cli users will be more aware of this feature and will take the effort to implement it on their production servers.
But if this is an educational feature why does this commit doesn’t change any documentation in ember-cli ?
How many ember-cli users that don’t read each pull request and change log will be even aware of this feature ?
How many of them will know what even tho their development environment is now more protected from XSS their production environment might might steel be exposed ?
How many users will know that even if they’ll implement this feature on their production servers IE8/9 and probably 10 and 11 unless X prefix will be set on the headers, will still be exposed to XSS since this browsers don’t support CSP ? all browser Ember actively supports.
I think documentation should be a higher priority than it is now. this will be beneficial for both the developers and ember-cli that will get more people improving its code.
I don’t think it should only be you and others who currently know the inner working who write this documentation. as a community we should all pitch in and try to improve the documentation but more people will do it if this would be declared as a priority by you and other main developers
I think the biggest thing you’re missing is that making software < making products. The terrific thing about CLI is that you don’t have to know how most of the stuff is wired together until you want to do something different, then you only have to learn that part. I didn’t touch the environment file until I had to deploy to a non-root directory, and then I was just changing one clearly labeled line. I didn’t even know what the rest of it was doing until I want to add one of the loggers, and then it was pretty straightforward. In the meantime, I was busying myself with making products instead of reading documentation. I may be neither, but I’ve found that “JIT learning” is scorned by good developers, and embraced by great ones.
I still don’t know what half of the stuff in CLI does, all I know is that I can make stuff faster that runs better, which I believe was @stefan’s goal.
I think ember-cli is a great tool but its documentation is lacking. it seems like most of the documentation effort, is going toward basic use instead of understanding the concept.
Same with every open source project, and that’s not necessarily the worst thing. The easiest way to understand it is to start using it, which they’ve made incredibly easy to do. Having a “contributor primer” that talks about the structure of the code would be a cool feature, but I don’t know that it should be the highest priority.
I think improving documentation in the Ember ecosystem is a great goal and something worth doing but I don’t like the tone of your post and I find the thesis a little hard to believe. In any case, I actually think it’s never been easier to get started writing fast and robust Ember apps, and you should give ember-cli another try, but this time, building a real app.
@yonjah I’ll point out since @stefan didn’t directly. ember-cli is nowhere near complete. There’s a reason that the current version is 0.0.46 and not 0.1.0 let alone 1.0.0.
If you look through the ember-cli issues there are many that reference incomplete or outdated docs. There are many reasons for this, the main one being that ember-cli is changing just about every day. @rwjblue and @stefan have commented over and over that it’s something they’d love help on because they are focused on completing features and fixing problems. Personally I think that’s a much more important goal.
Once the API stabilizes, the docs will be improved immensely and kept as up to date as possible. Until then, this project is in HEAVY development. You have to know that getting in, it’s one of the first things in the readme. Perhaps it could be elaborated on, but it’s been mentioned many times. As awesome and great as this project is, it’s going to be changes, and you’re going to have to suffer through upgrades until it’s marked as stable.
If you want to criticize ember itself, go at it as it’s stable. Criticizing ember-cli is way to early to do because I can pretty much guarantee that everything you mentioned is going to be different by the time it’s 1.0.0
Absolutely agreed. I would love to have more help with documentation.
What is standing in anyones way? All of ember-cli’s source is freely available.
This is precise what the ARCHITECTURE.md in the root of the repo is intended for.
As mentioned in the addon’s readme (and in that PR) the addon itself is definitely more of an educational thing, but to enable CSP at all required many changes in ember-cli. The actual changes needed so that this simple educational addon could be used were done in Do not use inline script tags. by rwjblue · Pull Request #2058 · ember-cli/ember-cli · GitHub.
Nothing changes in the way you use Ember CLI, you now get errors/warnings in your console if you violate the CSP policy (which has a sane default value). As far as CSP documentation, many many sites and tutorials exist to explain this, not sure we should reinvent the wheel here.
The CHANGELOG and release notes should be read by anyone upgrading an application.
CSP is NOT a silver bullet to prevent you from having to deal with XSS attacks. It is just one more line of defense. As of Bump CSP addon version. by rwjblue · Pull Request #2076 · ember-cli/ember-cli · GitHub, both the normal header and X-* header is sent by the addon.
Awesome! Lets stop talking about an extremely negative blog post and instead focus on your pending PR fixing things up!
We have ALWAYS been both grateful and supportive of documentation efforts, and will continue to do so.
incorrect, by building your app in a CSP strict environment you:
Firstly, this is not an educational feature. (See above)
Secondly I am glad you noticed the lack of docs: https://github.com/stefanpenner/ember-cli/tree/gh-pages is a great places to submit such documentation. As a continuation of your post, I welcome your writing skills in the form of helpful material that you noticed is lacking.
as mentioned several times: https://github.com/stefanpenner/ember-cli/blob/master/ARCHITECTURE.md If you have question about specific architectural questions that is missing. Take a chance, open a PR, and iterate with the community on improving that document.
This comment is concerning and I am unsure how to respond.
Roughly 1/5 of all commits to this project are documentation related. http://www.ember-cli.com/ and the Architecture.md did not appear without effort or priority, but they are the result of an ongoing community effort to improve the experience for all.
If I have somehow conveyed that documentation is not a priority, please elaborate I would like to ensure others do not feel this way.
just to be sure, my public declaration of documentation priority:
https://twitter.com/stefanpenner/status/514247780593070080
this discussion has value, we should ensure the value makes it out of this forum and into real tangible value for the community.
When you (or anyone) encounter documentation lacking, or confusion on a topic. Open a pull-request to the website. This PR should contain an outline of the confusion in the form of an explanation. Feel free to leave out the parts that are confusing. Then you, me and the community will in collaboration flesh out a well form piece of literature on the topic.
Hopefully we can all start documenting moving forward: https://github.com/stefanpenner/ember-cli/pull/2106
We should encourage Ember developers to document as well: https://github.com/stefanpenner/ember-cli/issues/746
I don’t know Ember or Ember CLI, but my first task on a new job is to make a pre-existing ember app CLI-compatible, so I understand your frustration. Luckily we are all programmers. HGPA
Continuing the discussion from I started a small blog series about some isues I find in ember:
Thanks that’s great Info. I completely missed this file. I tried to dive into some commands and tasks code but I’m still fighting to find some of the build logic (I hope I’ll have more time in the weekend).
Continuing the discussion from I started a small blog series about some isues I find in ember:
I’ll try to help as much as I can. The fist thing I want to do is to understand is the ES6 build process both of the app and ember-core. I’ll try to add documentation as I go along.
That’s awesome !
Thanks for all the replies I’ll probably have more questions as I go along
“There’s a reason that the current version is 0.0.46 and not 0.1.0” - Exactly!
Ember CLI is a fast moving target, but already most of the essentials are well documented. Lately I discovered the docs updated on how to create blueprints and addons 
There are many samples out there you can use as a baseline… Ember CLI makes you much more productive, it is all about leverage while still allowing you to dig down at a deeper level to make it fit your needs. This is what open source is all about 