Only good test coverage will give you confidence (more or less)
Not looking for confidence in the deps, just what they are and why I need them.
Aren’t the guides and other docs where you go first to learn about ember?? That’s where I’d first go looking for such information (actually ember-cli.com because I know of that site).
That’s what I figured, but wanted to point out that’s how I took it and others could too.
2 Likes
If u use vscode, try this plugin: npm Dependency Links - Visual Studio Marketplace
Hover over a dep in package.json, command click it, see docs.
4 Likes
To me it just seems lazy if a developer can’t just go to the folder and read the doc or visit the GitHub page. Not badmouthing you or anything. It’s just overkill expecting any npm module to have a write-up on all their dependencies when almost all npm libraries have documentation easily available within it’s directory. Like, “here’s documentation for your documentation.”
1 Like
There is a misunderstanding. I don’t mean to have a description of every used npm package inside ember documentation, it would be off topic and overkill. I just think that is reasonable to wonder why my app “must” include some of these libraries, which functionality will my app loose if I remove that library from the dependencies list. It was said that those dependencies are meant to be app’s dependencies and not ember’s dependencies because a developer, in some particular cases, might choose to renounce to it, but, I don’t know if I want to renounce to any of those or not, because I dont know for what they are used: not the purpose of the library itself, but it’s purpose in my app. I try to make it a bit more clear: if ember didn’t need that library at all, it would not be there, right? It doesn’t make sense to insert a “default” dependency in an app just 'cause it’s cool and maybe we would like to use it, but it actually has nothing to share with the framework. So, since it is there, the framework uses it in some way, or the lib is a part of the framework itself, but anyway it is not strictly required by every app. To be aware about the effect toward the framework of removing that library from my project, I must know in which way it is involved, and the best way of discovering it is to have it explained by who decided to put it there. What do we prefere? Read the readme file, dig in it’s github repo and try to guess that, or have it explained in few rows on the official framework docs?
- May I suggest double checking that you’re clear on the difference between dependencies and devDependencies and the purposes of both?
- “renounce” seems like a pretty strong word, maybe?
- Awesomely enough, there are a variety of options for making this idea happen:
- you could visit the #-team-learning channel on Slack and chat with us about what would improve this experience for you (tbh it would not surprise me if this became a blog post by @jenweber)
- you could file an issue on github.com/emberjs/ember.js
- you could write an RFC to propose a different way to do it
- you could open a PR that makes the changes and explains why
2 Likes
Man this thread makes me wish we could easily do inline comments in package.json. In theory, we could move some things to optionalDependencies to auto document this… that being said that will likely open a can of worms.
In light of that, I believe we should put up a guide/doc page describing the default addons, and if they are optional or not. Although this is slightly more work for us maintainers short term, I believe it clearly delivers good long term failure.
1 Like
@melsumner in my opinion if we elaborate your answer and write it under the Dependencies section of the guides, it would be already enough to stop people asking questions about it, and eventually learn something more. Something like
You may notice that there are some packages included in your app as per default.
They are needed to run your Ember application, anyway, under certain circumstances,
you could choose not to use some of them in order to ...
If you think this is your case and/or you want to learn more about it, ...
One simple text, for everyone and for ever. What do you people think?
EDIT
I know this looks stupid to many of the people with a big confidence and years of experience with npm and ember.js or other frameworks, but people like me, coming to web developing from a different programming enviroment, may follow this path:
- I must develop a big web app from scratch, ok, I need a framework.
- After some googling I found Ember.js being one of the best, and for this and that reason I believe it’s my choice.
- I follow the guides to get started
- Ok, I am ready to start a new app, let’s do that!
ember new hello-world - Why is this taking so long time?
- Why is this folder already sooooo big for an empty application?
- What are all those modules? Why I need them, let’s go find some infos.
My point is to have it explained on the guides in some way, which will make people spend less time on the last step. If @rwjblue and @stefan believe that adding a why about every single main dep will be a long term mess, is better to avoid it, but still… I keep thinking that for those like me who just landed on this planet it is easy to end up with this question, and to have an easy findable, official answer will make the difference.
I think it’s reasonable to do a why/what/how for each dep. my intuition is that the relatively small cost curating that, should be paid for easily by how much it would empower users. Even just in support load…
To be honest, what you described is always true for every other programming/framework environment. And to be frank, this issue is actually within the scope of npm, the package management system of node.js.
In the world of ember, every dependency is already described and documented correctly in the way of every npm package did. If some of them don’t, we should ask/issue correspondingly.
Sooner or later you will found, even if you remove all optional packages from default dependencies list, it still took a long time to install/update and the node_modules folder is still significant. It is just what the current status of node.js/npm is.
- If you need one line version of introduction, every package has its own
descriptionfield in itspackage.json - If you need full information, every package has a readme file, and you can find more on it.
- If you want ember.js to provide an overview page, I don’t think it can do better than the two options listed above, plus, since every dependency changed continuously, people need more time to track them down and to update the overview page
I completely understand your feelings as a newcomer, but I believe it is the “cost of growing up” because every language/framework has the same problem, can you name one who does it better than others? I would love to learn how they did.
Sorry to be so direct, but I actually think that you seriously misunderstood the whole discussion. I never asked for an other package description and I am not questioning the speed of npm to install the packages or how many they are. I am not able to explain my idea or you did not read carefully the posts above, in any case, I don’t know what to answer.
This is actually what you asked previously, right?
What are all those modules
Answered in their descriptions
Why I need them
Answered in their readme or issues
let’s go find some infos
That is what I mean of “cost of growing up”, people will or will not provide you a one-stop info, but A) it is never enough to make everyone happy and it is easy to be outdated; B) it is important to know how to “go find infos” in the context of npm, because ember is just a subset of npm package system.
Please don’t feel sorry for me, I’m not judging you or anyone on this, it’s just my thoughts.
And talking about default packages I wrote:
This is the question. You are focusing about an example I wrote to make people understand from which kind of experience this question could be raised.
For me, it’s less about knowing what each package does individually and more about how and why the package is needed and used in an Ember project. With some of these default packages, it is not easy to see where they are required in the codebase. And because its not as transparent, it can be difficult to understand why they are necessary.
I would think that the default packages would just be listed as direct dependencies of ember-cli or ember-source (optional or not). And the build will do the necessary tree shaking required based on which packages are actually in use. If that were the case, I think that would help a little. Or at the very least, make upgrading easier. Because the consumer wouldn’t need to keep track of updating each package manually as new versions of Ember are introduced. I realize the Ember team provides package upgrade instructions and automated scripts to upgrade, but the steps are a little too involved and can easily be done incorrectly. The upgrade paths also dont really educate us on why the default packages needed to be upgraded or included.
1 Like
But not why they are included in the projects deps by default from ember-cli. That is the key question here. IMO, this is more of an onboarding thing than anything. If I was new to ember and created a new project, I’d wonder why my project has all those. I think it’s a fair question to ask, why ember-cli has decided to include those by default, which is not answered by the package’s README.
1 Like
I’m spit-balling here but what about adding a section to the ember-welcome-page addon? As an addon it has the ability to parse the apps’ package.json, resolve node_modules, and compile a list of descriptions. I like this because that addon is removed after the initial im-new-here wears off. And it would give the addon more usefulness then just being something is neat the first time then removed immediately. Plus it would offer a one stop place to link to the READMEs and is always up-to-date without any maintenance concerns.
3 Likes
This is a great idea and I like it a lot. But for those who gloss over the welcome message or start modifying the application template right away might not see it. They would probably then go to the guides/docs to find the info, so something in the guides/docs explaining the welcome page is the place to find that information (and how to see it if they already removed it) would be helpful as well.
I don’t understand which part is not answered by readme, “to include” or “by default”?
Let’s take ember-cli-sri as an example, in its readme, the first and second paragraphs are:
does it answered why it is been included?
An addon (almost everything in default blueprints are ember add ons) is been included by default doesn’t means you can not remove it, and its readme tells you exactly which functionality will loose if you remove it from the dependencies list.
1 Like
If I read this thread correctly the complaint is not that the READMEs answer the question of why but that they are in the READMEs of the modules and not in a central location. If I were to paraphrase it seems as though the npmjs.com repository is not an acceptable location to store the answers to why a module is needed or not.
To address this the original author is suggesting currating the READMEs in a location he/she can google or discover from emberjs.com without using npmjs.com. And that this could be resolved by a script that curates the package.json of each module along with their descriptions and links to the GitHub READMEs.
I believe my idea to leverage the ember-welcome-page addon to do just this might alleviate the concerns of the original poster.
Please correct if I have this summary incorrect.
Okay, I apologize to you for blurring your main subject, but my points still remain.
The reason why these add-ons exist is actually in the readme document, but people are always waiting for others to sort them out.
Of course ember community can improve this, but they also need to consider their maintenance costs. And it is not only ember’s responsibility to teach people how to find useful information, but also the responsibility of the entire npm ecosystem, like I said previously, ember itself is just a subset of npm packages. Sooner or later, you still need to learn to be self-reliant as long as you’re writing javascript applications, no matter using ember or any other tools/frameworks.