Tutorial for managing stylesheets, exporting public API, block form addon templates

[jenweber]

I would like reviews and feedback from at least these two levels:

• People who have never written an addon or who can put themselves the shoes of someone like that - please tell me which parts don't have enough detail or use unnecessary/confusing jargon
• Experienced addon authors - please share which parts I glossed over too much, plus if there are any "aha moments", gotchas, best practices, or mental models that helped you out

Rather than reviewing the diff, new contributors may want to start reading the addons guide from the top and then add comments inline here

Many thanks ❤️

P.S. @sivakumar-kailasam if you can have a read through the whole addons.md file, I think this is probably the right time.

[ijlee2]

@jenweber Thanks for working on updating this tutorial. I'm new to making an addon and have been wanting to make one soon.

I read the tutorial and followed along by writing code. Here are some observations that I made:

Trying out the addon template in an app

• Between steps 2 and 3, I wasn't sure what the difference between "addon directory" and "main addon directory" was. If they are referring to the same, maybe stick with "addon directory"?
• In step 5, I'd be more specific and mention "devDependencies" as the location, given that step 1 talks about our need to use "dependencies" and not "devDependencies".
• In step 6, I'd mention doing install in the Ember app.
• In general, I think steps 1-3 can be grouped and placed under a sub-header (addon), and steps 4-8 under another (app). I think this would help readers distinguish what to do in the addon folder versus in the app folder. I'd also end each step with a period for consistency.

Making a UI component available in block form

• Grammar fix: "Simple form is useful when the app developer should provide". However, I don't think this sentence, as is, sounds natural. Maybe "Simple form allows the app developer to provide [...] to the addon, while block form allows the app developer to pass in their template, content, and interactivity."?

CSS stylesheets that require importing from addons

• After saving app/styles/app.css, I had to restart the server to see the import take place and the CSS change. I was a bit surprised because, prior to this step, the changes that I had made in the addon were applied to the app automatically.

Providing public API methods in the addon

• I think it may be good to include the link to Semver in "Semver is a cross-program-language" and remove the sentence "Learn more about semver here." I'm thinking so because a hyperlink to "here" doesn't mean a lot.

Organizing public API code

• Should "our-app-name" be "our-addon-name" instead?
• I think it would be good to keep the addon name consistent throughout the tutorial. It has been referred to as addon-name, my-addon-name, our-addon-name, and ember-addon-name.

Miscellaneous

• I think a main point that we can drive in the beginning of the tutorial is that, if a developer has worked on an Ember app before, it will be easy for them to create an Ember addon because there are many similarities between the two.
• I tried out --pod when creating a component in the addon and it worked!

Thanks again!

[jenweber]

Thanks again everyone for such thorough reviews, explanations, and help! You are awesome.

I think I have incorporated all the feedback, and it is time to publish the RFC! Work on these guides will continue in a different repo that follows the same structure as the main Ember Guides.