★ wanayoo — archive 1999 https://github.com/ember-cli/ember-cli.github.io/issues/111Nouvelle recherche | Portail wanayoo
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Quest Issue] All I want for Christmas is some documentation! #111

Open
martndemus opened this issue Dec 2, 2016 · 14 comments
Open

[Quest Issue] All I want for Christmas is some documentation! #111

martndemus opened this issue Dec 2, 2016 · 14 comments

Comments

@martndemus
Copy link

@martndemus martndemus commented Dec 2, 2016 •

Hi all! I'd like to make Ember CLI's Christmas extra special by crowd sourcing some effort into documenting the various unknowns around Ember CLI.

Ember CLI is awesome. Broccoli, the main driving force behind Ember CLI is awesome too. Together they form the best CLI for managing and building browser JS projects in the world.

Sadly a lot of the awesome behind Ember CLI is very underdocumented or the documentation is very hard to find unless you know what you are looking for.

I'd like to try and do what @chancancode did for Glimmer 2 integration and see if a big centralized quest issue could motivate a group of people to concert effort into improving Ember CLI's documentation.

Here's my wishlist:

  • Better documentation how to update Ember CLI
    • determine acceptance criteria
    • pr

Ember CLI's documentation on this is very sparse, upgrading is quite a bit more involved than the Ember CLI website shows you. A more detailed guide would be very welcome.

  • How to configure Babel

Relevant project: ember-cli-babel
There is a little bit of documentation there, but could be expanded greatly. Things like how to turn on/off certain ES2015+ features transpilation could be improved. The documentation is also hard to discover, there is no mention of this in the official ember-cli.com docs.

  • How to include Babel / NPM dependencies in your app.

Including Babel dependencies is quite well documented, but seeing there is a recent move of all dependencies to NPM, we could use some documentation on how to include dependencies from NPM.

  • Code mods

People have been making code mods to migrate pieces of code. It would be amazing to have clear cut documentation on how to do this, as learning this skill is pretty much limited by copying code from other projects right now.

See:

There is some documentation for this, and you can find it if you search really hard for it. But it's scattered all over the place. It would be great if the documentation for this could be more findable and concentrated in a single place.

..... I'm sure I or someone else will think of another thing to add to the wishlist.


Please like, share and leave a comment below. Let's give @stefanpenner an extra special Christmas!

@Turbo87
Copy link
Member

@Turbo87 Turbo87 commented Dec 2, 2016

How to configure Babel

we might want to think about this in the context that we will want to upgrade to Babel 6 at some point in the hopefully near future.

How to include Babel / NPM dependencies in your app.

I'm assuming you meant "Bower" here?

@cibernox
Copy link
Contributor

@cibernox cibernox commented Dec 2, 2016 •

I can do the babel configuration story. I've been developing with many features disabled (mostly because I hate debugging transpiled e-c generators) and I haven't found a single issue so far.

@Gaurav0
Copy link
Contributor

@Gaurav0 Gaurav0 commented Dec 2, 2016

Better documentation how to update Ember CLI

IMO this is still too difficult. ember init offers a bunch of puzzling choices and almost every real application ends up manually patching because we have changed our default files in ways that are not compatible with any of its offered options.

git merge does an awesome job at figuring out what can be consumed and passes the minimum to the user as a "Conflict", and editors and diffing tools work well with it to make conflict resolution relatively easy in most cases.

I think ember init needs to be more like git merge.

@abuiles
Copy link
Member

@abuiles abuiles commented Dec 3, 2016

Code mods

My idea for a while has been to replace the current implementation of ember-watson, with jscodeshift -- so it will be only a wrapper to it. The amount of people using codeshift + docs give us a good starting point for something others can extend.

Unfortunately, my bandwidth is pretty limited at the moment so I can't do it myself, but if someone can help, I'd be happy to give support as much as time allows.

@stefanpenner
Copy link
Contributor

@stefanpenner stefanpenner commented Dec 3, 2016 •

@martndemus I have updated your issue slightly, so that it is in the form a checklist. This should help track progress. Some of the ideas seem good, but for a quest issue they seems under specified. I have also created check marks to track those things.

@stefanpenner
Copy link
Contributor

@stefanpenner stefanpenner commented Dec 3, 2016

Better documentation how to update Ember CLI
IMO this is still too difficult. ember init offers a bunch of puzzling choices and almost every real application ends up manually patching because we have changed our default files in ways that are not compatible with any of its offered options.

git merge does an awesome job at figuring out what can be consumed and passes the minimum to the user as a "Conflict", and editors and diffing tools work well with it to make conflict resolution relatively easy in most cases.

I think ember init needs to be more like git merge.

this is true, but requires its own RFC. Lots of little details that turn out to be tricky.

@stefanpenner
Copy link
Contributor

@stefanpenner stefanpenner commented Dec 3, 2016 •

How to write Ember CLI addons / Broccoli Plugins.

The acceptance criteria for this issue is not terribly clear. Documentation does exist, but it is lacking some scenarios: https://ember-cli.com/extending/#developing-addons-and-blueprints an RFC or similar describing what would improve it would help make this actionable.

@stefanpenner
Copy link
Contributor

@stefanpenner stefanpenner commented Dec 3, 2016

@abuiles got any cycles re improving codemod docs, as you are the original master mind behind ember-watson you have have thoughts/ideas.

@Gaurav0
Copy link
Contributor

@Gaurav0 Gaurav0 commented Dec 4, 2016

Some quick features of ember-cli addons there is little or no documentation at ember-cli.com for:

  1. Where to put CSS (or less or sass) you want automatically included in dependent apps/addons
  2. Where to put CSS (or less or sass) you want dependent apps/addons to be able to opt in to.
  3. Where to put assets you want automatically included in dependent apps/addons
  4. Where to put assets you want apps/addons to be able to opt in to.
  5. The test-support directory and what it is for.
@mohamnag
Copy link

@mohamnag mohamnag commented Feb 1, 2017 •

I was trying to create my first ember addon and bumped into following points which where not clear on the docs:

how to include depending addon:

in one place docs say:

If your addon depends on another addon, install it as a dependency in your package.json

and in blueprints it says:

addAddon(s)ToProject Adds an addon to the project’s package.json and runs its defaultBlueprint if it provides one.

so what should I exactly do? is adding to package.json enough? or should I add it to the blueprint too?

how to run blueprint on linked addon

once docs say

Remember that npm link will not run the default blueprint in the same way that install will, so you will have to do that manually via ember g.

but when I run the ember g <addon-name> (<addon-name> replaced with real name) on linked application, I get this:

installing <addon-name>
The `ember generate <entity-name>` command requires an entity name to be specified. For more details, use `ember help`.

then I try it with doing ember g <addon-name> aaa and it seems that it works. So which way is correct?

@Gaurav0
Copy link
Contributor

@Gaurav0 Gaurav0 commented Feb 1, 2017

The key question is does your addon depend on another addon, i.e. does it require() it. If so, you must use the dependency in package.json. If, on the other hand, you want an addon to be installed when your addon is inside a project, but don't need it to run the addon itself, then add it to the blueprint. This is likely if your addon is a plugin for another addon.

@mohamnag
Copy link

@mohamnag mohamnag commented Feb 2, 2017 •

Ok, currently I cant imagine a case where my addon depends on another but does not require it. But in my scenario the addon contains some templates and I want to force user to do i18n using ember-intl so I suppose I have to add it to the dependencies in package.json.

however I found out when I install my addon on a host application the blueprint of ember-intl is not run on that host app, so lots of config and so on is missing. Is this intentional behaviour or am I missing something?

@Gaurav0
Copy link
Contributor

@Gaurav0 Gaurav0 commented Feb 2, 2017

@mohamnag If you need the blueprint to run, use addAddonsToProject. I don't see require('ember-intl') anywhere in your addon, so I don't think you need to put ember-intl in dependencies. Just add it to devDependencies if your dummy app will need it.

@mohamnag
Copy link

@mohamnag mohamnag commented Feb 3, 2017

it is not only for dummy app, it is for templates delivered by the addon itself. So I will add it to blueprint, but these information are still worth going into the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants
You can’t perform that action at this time.