I started a small blog series about some isues I find in ember

[rwjblue]

@yonjah

I think ember-cli is a great tool but its documentation is lacking.

Absolutely agreed. I would love to have more help with documentation.

@yonjah

But Ember users are developers and they should have a clear path to research farther if they want to.

What is standing in anyones way? All of ember-cli’s source is freely available.

@yonjah

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

This is precise what the ARCHITECTURE.md in the root of the repo is intended for.

@yonjah

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.

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.

@yonjah

But if this is an educational feature why does this commit doesn’t change any documentation in ember-cli ?

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.

@yonjah

How many ember-cli users that don’t read each pull request and change log will be even aware of this feature ?

The CHANGELOG and release notes should be read by anyone upgrading an application.

@yonjah

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.

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.

@yonjah

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.

Awesome! Lets stop talking about an extremely negative blog post and instead focus on your pending PR fixing things up!

@yonjah

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

We have ALWAYS been both grateful and supportive of documentation efforts, and will continue to do so.