ember-learn / cli-guides Goto Github PK

It can be confusing to constantly read references to yarn and npm. It would be much simpler for the reader to select npm or yarn once and read the whole set of guides in that context.

As mentioned in ember-cli/ember-cli#7021 (comment), the CSS portion of stylesheet compilation is documenting behavir that no longer happens, and should be updated.

It would be helpful to have a test/linting for the following:

• "JavaScript"
• "Ember"
• "Ember.js"
• "npm"

We still talk about ajax in a few places.

ember-decorators/ember-decorators#134 (comment)

Ember-CLI considers dependencies in an addon to actually be addon dependencies, and devDependencies to be the Dummy app's dependencies.

This case looks to be the same than having to set ember-cli-htmlbars in the dependencies for component addons.

It may be good to document this detail when talking about the Dummy app.

I don't think this belongs in "writing addons" because this is mostly about importing and customizing dependencies which can either be done in the app via ember-cli-build.js or in the addon via index.js. How exactly it should be organized probably deserves further discussion on discord. There is a discussion about this on Discord here: https://discordapp.com/channels/480462759797063690/480777444203429888/499943437626507274

See also my review here: #19 (review)

3 things for debugging that I do that others might find useful:

• node inspect
• DEBUG=* which is extremely noisy, but once you see that and then figure out that it's using the npm debug package (or have @bendemboski tell you 😄)
• npm link and isDevelopingAddon() { return true; }

Documenting these under Advanced Use > Debugging with some examples would be great

cc @jenweber

Couple more cookbook topics that the guides don't cover (afaik)

1. Adding files during the build process (especially if the contents need to be fetched async)
2. Changing the contents of a file during build (useful for static JSON in public/ for example

As noted in #73, to add checks for broken links using remark, we need to run Node 8 in our CI.

After #76 is merged, we can add it!

cc @maxwondercorn

I never knew this page existed and I've always been confused about config/targets.js and how it actually gets consumed. I think it should be moved to the CLI guides

https://guides.emberjs.com/release/configuring-ember/build-targets/

Seems the index pages all trigger a request to a non-existing .json file:

There's no documentation on how to test an addon with diffferent runtime configs.

I see some addons doing something like generate multiple apps with different config/environment.js files and run the test suite for this apps, but I have no idea how to do this right.

Now with Firefox working in headless mode we should document this as a part of the guides.

Original inspiration: https://twitter.com/Romgere_dev/status/1050702153302593536?s=19

backstory

We use ember server --secure-proxy false --proxy https://127.0.0.1:4000 for local development. We proxy to a node.js application as our API server at port 4000. A few of our endpoints stream a downloaded file to the browser. When I switched to using ember serve, over a custom configured apache, these endpoint downloads failed locally.

main problem

I searched for about 6h on the "right" way to do this in my ember project. This surprised me as basic configuration in ember should be seamless. Additionally, I did not expect to have to override the default ember server behavior by defining a proxy using ember g http-proxy my-download-path http:127.0.0.1:4000. If this tripped me up, I think it could scare other users away. I think we need to capture how to do this and/or examples of using http proxies with ember-cli

solutions

• Should this be a topic in the advanced use?
• More general recipe somewhere else?

Thanks for your interest in helping with this project! We are porting over content from ember-cli.com, editing it, and writing new things. This project is part of an RFC

Choose a task, comment on this issue to say which section, then open an issue with the same name. The newly opened issue is the best place for Q&A about the task. Please read CONTRIBUTING.md before starting to write. Note that you should not have to create any new files. If you need help deciding where your content belongs, ask a question on the issue and @ me.

We will accept PRs that partially address topics, add comments with suggested content, or start to define subheadings within topics. Small PRs are awesome! The goal is to be quick to PR, quick to merge, and allow for some churn later on.

Note on respecting copyright - It is ok to copy/paste content over from ember-cli.com. It is not ok to copy and paste content that you didn't write that came from blog posts, articles, tutorials, etc. whether paid or free. Exceptions are if the license allows it or you have written permission of the author via a comment on an issue in this repo.

Goal - Ship by the end of November!

Open tasks that need volunteers:

• Pick a markdown file without content and add suggested headings (many people needed, name a subject and it's yours. Make it clear in your comment or issue name.)
• Update Asset Compilation
• Update Upgrading section (separate PR)
• Port over up-to-date sections of Blueprints. Remove/edit outdated content. Recommended for experienced addon authors.
• Go through developing addons and open an issue listing points missing from the Tutorial
  • After the audit, PR the additions (should be very small, 5 sentences max)
• Write a section on including assets in addons - Greenfield, recommended for experienced writer/addon author.
• Write updating addons section in the "Upgrading" page

WIP tasks

• Port over Environments. Mostly copy and paste from this source code @ddoria921

Nice to Have

On hold (no volunteers needed yet)

• create a mapping of ember-cli.com pages to our urls
• End to end prose editing sweep after MVP is reached
• End to end technical review
• CI
• Staging deployment
• clean up some stylesheet quirks
• handle problems with incomplete urls
• alpha deployment to cli.emberjs.com
• implement redirects in ember-cli.com (after Jan 1st?)
• add cli team as maintainers for the github repo

Completed tasks

• align RFC topics with the table of contents/file structure - @jenweber
• write basic beginner content for using the CLI and making an addon - @jenweber
• app structure, deploy pipeline, scaffolding, etc - thank you so much @mansona
• Port over watchman instructions. Mostly copy and paste from this source code #4 @sandstrom, includes review and updates
• Port over Windows-specific instructions on ember-cli.com. Mostly copy and paste from this source code @Gaurav0 #6
• Port over Editors. Mostly copy and paste from this source code @cah-danmonroe #6
• Automated testing by @aklkv #9
• Port over Asset Compilation (unedited). Mostly copy and paste from this source code @Gaurav0 #18
• Port over Common Issues. Mostly copy and paste from this source code @BradenLawrence #12
• Port over Upgrading. Mostly copy and paste from this source code @DanMonroe #11
• Port over managing dependencies. Mostly copy and paste from this source code @BradenLawrence #19
• Update or rewrite Managing Dependencies (a separate PR from above) @jenweber
• Rewrite Deployments - greenfield, recommended for experienced writers @jenweber

Now is no information in the page about what is send with analytics enabled.

We should add this info https://github.com/ember-cli/ember-cli/blob/master/docs/analytics.md in the Appendix section.

In several places throughtout these guides, we show the file paths for components as components/my-component.js and templates/components/my-component.hbs. These references need to be updated to reflect the new structure where both hbs and js files are in components. Since the cli guides are not versioned, we should show both classic and octane layouts.

Here's the page to update: https://cli.emberjs.com/release/advanced-use/project-layouts/

The work on the component generators is part of another separate issue, #134, so just edit the layouts page for this PR.

This work should target master and will be merged with 3.14.

The number 1 thing I go to the CLI website for is when I’m writing an addon and need to refer to the different hooks available. On my phone, i opened the new website and saw an API Reference in the header menu, but looks like it goes to the Ember API. Not sure if this is intentional or a bad link, but would be great to have a reference to the addon index.js API reference somewhere.

I'll do this one as well.

Looking through the guides, I think the nav structure could look like this:

Intro
  - Ember CLI
CLI Commands
  - /index (links to full API docs and references `--help`
  - new
  - addon
  - install
  - serve
  - build
  - generate
  - test
Build Pipeline
  - Builds & Rebuilds
  - Asset compilation
  - Dependencies
  - Addons (for merging behavior)
  - Plugins (Broccoli intro)
  - Looking Forward (Ember Auto Import & Embroider)
Addons
  - Structure
  - Dependencies
  - Blueprints
  - In-Repo
  - Documenting
API Documentation
  - CLI
  - Addon (aka `index.js` export)
Configuration
  - .ember-cli file
  - ember-cli-build.js
  - ember-cli-update.json
Troubleshooting
  - Windows
  - Vagrant
  - Debugging
  - Performance
  - Updating

Some other things that I can't find a place to put are

• FastBoot: i.e. how to handle FastBoot cases without including FB as a dependency and how to write tests for FastBoot
• Testing (running tests at localhost:4200/tests, the fact that the app is mounted in a div, not an iframe, etc)

Issue #3 brings us to MVP. Here's the plan for what comes after. Our goal is to empower new addon authors.

• write a second addon authoring tutorial. It can focus on wrapping an existing library.
• finish reviewing and revising legacy content
• cover common configurations
• link to or import some pieces of Broccoli docs
• ???

cc @aklkv

It is confusing that index.html is missing from the explanations.

Issue to track potential ember-data name change per #69. Also reference ember-learn/guides-source#184.

In #107, there was discussion about making the name consistent across websites, but we need to take a methodical approach to be successful.

This issue is to remind us that we haven't done that work yet, and we should.

The next steps are to write up a doc describing what should change, why, where, and when, as well as showing how the name will look in various scenarios. For example if a sentence starts with ember-cli, what does it look like? Etc.

The guide page titles are inconsistent with both title case and sentence case. Other guides are title case. Creating issue so it's on the list.

In safari on iOS, when i click the “next” article link as I’m navigating the guides, the page jumps to the top, before the content changes. It makes it feel like the link didn’t work, so I start scrolling down again, and then the content magically changes, which is jarring.

We do not currently have a place to redirect to for some of the content from the old site. It has the following endpoints:

/user-guide/#using-modules
/user-guide/#naming-conventions

With the Broccoli 2.0 implementation complete, we should ensure that there is an MVP for documentation in the guides. In addition to a basic introduction, the guides can link to the more extensive Broccoli documentation.

This issue is part of the Octane Edition of Ember.js.

Overall, I think the tutorial has most of the import topics covered but I think isDevelopingAddon should be mentioned as you won't see live reloads in your linked app if you make changes to the addon

Developers are used to seeing the reloads when working on regular ember apps.

Second, it's not part of old cli docs but should we mention ember-cli-github-pages as a way to deploy to gh-pages, similar to the way ember-cli-addon-docs is mentioned?

I can do a PR if there is agreement

Something like:

// index.js
module.exports = {
  name: require('./package').name, 

  includedCommands() {
    return {
      'my-special-command': {
        name: 'my-special-command',
        works: 'insideProject',
        description: 'whatever description here',
        availableOptions: [],

        run() { /* do the stuff */ }
      },
    }
  }
};

I recently got a question in the Ember Community Discord:

can someone explain to me what the difference between index.js and ember-cli-build.js in an addon is?

And here was my answer:

the index.js is the "entry point" for your addon and is where you add hooks if you're doing something intermediate or advanced with your addon. the ember-cli-build.js inside your addon is only used to build the dummy app when developing it locally and has no influence on what happens to the consuming app

It seems to me that as we have been training people that the ember-cli-build.js is the "entry point" to an Ember App it is likely that we will confuse people when they look at an addon. I assume we might be able to add a note to https://cli.emberjs.com/release/writing-addons/#addonfilestructure or somewhere that is explicit about the difference?

New docs are using both ember-cli and Ember CLI. E.g. there is a page title "The Ember CLI" and a subtopic header "Installing the ember-cli" at the same time. This should be normalized IMO. But I'm not sure which one to favor.

Please note that there is also an open discussion about renaming Ember Data to ember-data in guides: ember-learn/guides-source#184 IMO this should be consistent between Ember and Ember CLI docs.

Community feedback indicates that people need more guidance for using ember help and understanding the output, as well as searching for common commands. This is a frequently-requested feature of the CLI guides, so it's a big win if somoene works on this!

We should expand our list of commands and include more ember help examples.

To-do:

• Create a new page in the guides called "CLI Commands Reference" under "Advanced"
• Create a list of the commands and options available from ember --help
• Make sure whatever you do looks ok in mobile

This is related to #160

Known limitations:
Our Ember-CLI Guides are not versioned. Not all commands and options are available in all versions of Ember/Ember CLI. Rather than do something complicated, we should just show the commands for the latest version of Ember CLI, and a disclaimer that if you are an older version, you should use ember --help. An example of something that may not be available is the -gc in ember g component -gc.

In ember-cli (for a very very long time) it has been possible to have ember-cli use a different main entry point for the addon than what a normal require('my-package-name') would return.

The way to do this is to add an "ember-addon": { "main": "some-other-file.js" } to your package.json. Normal require invocation will look at the main entry point, and ember-cli will look at some-other-file.js.

One nice benefit of this is that if you make main be addon/index.js and ember-addon.main be index.js, "normal" node_module resolution rules apply for things in addon/index.js. This means that things like eslint-plugin-import and TypeScript can actual see and validate an import from the addon name (though not with nested paths).

For example, typescript (and eslint-plugin-import) would see that this is valid:

import Component from 'sparkles-component';

export default class extends Component {}

See rwjblue/sparkles-component#23 as an example.

The existing blueprints section covers the differences between classic and pods apps as related to blueprints. podModulePrefix is mentioned without a definition or reference.

Since pods are still used I wanted to link podModulePrefix back to its definition. It's defined in a section of the user guide that we have't brought over. The question is how do we handle pods in the new guides?

Until module unification lands, pods are still viable and I think we should include something. There's not a lot of content on pods in the old guides, so it's more than just copying the old content. There will be some rewrite.

I'd think a short section in Advanced use would be the appropriate location. I opened the issue for discussion

We have infrastructure to show the path of the file the sample corresponds to, as well as the type of file. For example:

```handlebars {data-filename=app/templates/application.hbs}
<h2>Welcome to Ember</h2>
```

For the cli-guides we should show the ember-cli logo in the top left just above the TOC.

As we are using guidemaker for the ember-cli guides we will need to make this a configurable feature of the guidemaker-ember-template so that any other projects using the same template can optionally configure this logo

Todo

• add a configuration entry for logo to the guidemaker block of the cli-guides https://github.com/ember-learn/cli-guides/blob/master/config/environment.js#L33
  • I guess it doesn't really need to be in the guidemaker block 🤔 but it needs to be somewhere in that config
• if the logo is configured it should be used in the template above the TOC
  • it might be worth putting it in this file that renders the left column: https://github.com/ember-learn/guidemaker-ember-template/blob/master/app/templates/version.hbs

In the CLI guides, we have a section on generating components, https://cli.emberjs.com/release/basic-use/cli-commands/

In Octane, ember g component gets you just the test and template. Flags are needed to generate a glimmer-based or classic component, and we should cover them in this guide. The CLI guides are not versioned, so we need to make sure that we explain both Octane and non-Octane behavior.

This work should target master and will be merged in at 3.14 release.

See issue in Guidemaker empress/guidemaker#3

I'm not 100% sure how to do this yet, but this came up on a recent FastBoot team call (thanks @mansona!) and I think its a great idea.

Can we brainstorm just how best to do this?

• blog post drafted emberjs/website#3703
  • blog post published
• PR opened to add CLI Guides to the navbar defaults of ember-styleguide ember-learn/ember-styleguide#115
  • merged
• After a merge & release of ember-styleguide, PRs to update the ember-styleguide versions used by:
  • The Guides
  • The deprecation app
  • The builds app
  • Statusboard? it doesn't use styleguide yet
• PR opened to add the link to the navbar for the API docs (not yet using ember-styleguide) ember-learn/ember-api-docs#576
  • merged
• PR opened to add the link to the navbar for the website repo (not yet using ember-styleguide) emberjs/website#3705
  • merged
• PR opened for a banner to the ember-cli.com site ember-cli/ember-cli.github.io#220
  • merged
• Change links within the Ember.js Guides themselves

See ember-cli/ember-cli#7908

#162 proposes expanding some commands guides. The best would be if we didn't need to provide so much info about interpreting the output of ember help. This issue tracks suggestions/ideas based on what we find while writing docs.

Add the API reference here: https://cli.emberjs.com/release/api-documentation/

There's probably some infrastructure work to make this happen automatically, but I think we can start by manually documenting the methods available to an addon in index.js? I don't think the methods change very often. Here's the list (taken from https://ember-cli.com/api/classes/Addon.html):

• config
• blueprintsPath
• includedCommands
• importTransforms
• serverMiddleware
• testemMiddleware
• postBuild
• preBuild
• outputReady
• buildError
• included
• shouldIncludeChildAddon
• setupPreprocessorRegistry
• preprocessTree
• postprocessTree
• lintTree
• contentFor
• treeFor

The previous ember-cli guide shows more information regarding the conventions of the addon structure.

• previous

• latest

When looking at ember-cli/ember-cli#8342, I wanted to know how test-support and addon-test-support works, but this info is not available in the new ember-cli guide.

I think the missing info should be added in the new guides as well. I can create a PR if someone suggests how it could fit best in the new guide structure.

Some suggestions to start the discussion:

• add the missing items into the Addon file structure section.

• create an Extended addon file structure section.

cc @jenweber

https://cli.emberjs.com/release/appendix/common-issues/

Installing Canary Build docs reference bower install, which I think is outdated info?

So, a ton of people use pods but we don't really cover it well anywhere, along the lines of "what are pods" and "how do they work."

I think maybe this content should go in the Appendix or Advanced sections.

I'll take a shot at this.

@cah-danmonroe has volunteered to help do this!

Part of work for ember-learn/guides-source#139