Interactive way to create new Ember apps #638
Conversation
This RFC introduces an interactive way to create a new Ember app.
MelSumner
changed the title
|
|
||
| ## Detailed design | ||
|
|
||
| ### Prior Art |
There was a problem hiding this comment.
maybe also Angular's Schematics.
There was a problem hiding this comment.
For ember-cli-create I looked into vue-cli at that time (that was shortly before they release vue UI (or however they named it)).
There was a problem hiding this comment.
I can update the language here- the prior art was meant to acknowledge the things we reviewed when working on this RFC, and does not intend to suggest that this is the only prior art that exists.
There was a problem hiding this comment.
I've updated the language here to indicate that the prior art listed here is specifically ones used for completing the analysis necessary to write this RFC.
|
|
||
| Starting a new Ember app or addon as we do now (at the time of this writing) will not change. If a user types `ember new my-app` they will still get a new Ember app generated in the usual ways. However, if the user types `ember new` they will enter into an interactive workflow that will ask them a few key questions about their application. | ||
|
|
||
| If a user were to type in existing flags that are also questions in the interactive workflow (i.e., `ember new my-app --lang en-US --interactive`), it will skip the question entirely. |
There was a problem hiding this comment.
I don't think this'd be a technical limitation. I can think of backing the interactive wizard with a statechart that would determine which questions to ask based on the presence or lack of flags passed at invocation time
|
|
||
| The general drawback with wizards is that it can lead to a large number of combinations, which increases the risk for fragmentation. We believe that we have limited this risk by limiting the number of questions asked, but it is still a risk and should be identified as such. | ||
|
|
||
| ## Alternatives |
There was a problem hiding this comment.
I think Angular schematics cover a large chunk of what we'd want out of blueprints, optional interactivity, and interactivity provided by addons + additional blueprints.
as part of this RFC, I'd like to see that path explored a bit, as it already exists, and would provide a lot of the future functionality
There was a problem hiding this comment.
@NullVoxPopuli Can you explain more? I think what you're describing is beyond the scope of this RFC, but I might be missing something.
| - `> app` | ||
| - `addon` | ||
| - `Please provide the name of your app/addon:` | ||
| - `Please provide the spoken/content language of your app/addon: (use arrow keys)` |
There was a problem hiding this comment.
Suggestion:
What is the default language of your app/addon? Please type your ISO639-1 language code. For example, the language code for English is "en" and the language code for Chinese is "chi". A full list can be found at https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes .
Motivation:
- Ensure equality for all languages
- Avoids discussion about which languages are "common"
- The wording for "default" gives people who are planning to do a multilingual app a path forward, whereas the text above doesn't.
There was a problem hiding this comment.
For no real reason I've always used en-US for the language codes, never simple en. Would this make any difference?
There was a problem hiding this comment.
I can imagine that this would for example determine the accent used by a screenreader if no default is set and different accents (e.g. British, US, Australian) are installed. But I would have to verify to be sure.
There was a problem hiding this comment.
For no real reason I've always used
en-USfor the language codes, never simpleen. Would this make any difference?
@MichalBryxi it can change things in small ways, like spellcheck, how things are pronounced, etc.
There was a problem hiding this comment.
I love to surprise people, that bar is a valid language tag for bavarian. Not only would I voluntarily turn on voice over to listen to that - but it also doesn't follow the usually expected de-bar format.
That said: I love the idea to ask for the spoken/content language as the question hints for what this is used. Contrary, I would answer de to this (because this is my mother language) but the app I'm building might itself be in english. Also the options seem nice (I say seem, because this is what experience will show after release).
|
|
||
| 1. We could decide on a different list of questions. See the notes from the [strike team discussion on May 20th](https://github.com/ember-a11y/core-notes/blob/ember-a11y/ember-a11y/2020-05/may-20.md) to review the other possibilities considered. | ||
| 1. We could make this the default for new Ember apps and add it in the appropriate version as a change. | ||
| 1. We could have this workflow be opt-in only, via the `--interactive` flag (e.g., `ember new --interactive`). Using the `ember new` command would error and trigger the help workflow (which would be updated to include the `--interactive` flag). |
There was a problem hiding this comment.
I'm always up for "sane defaults", which from my experience makes the flow more straightforward, expected (guessable) and more pleasant to use. In this case I see the sane default option the originally proposed one ember new => wizard.
| ### Question Rubric | ||
| We intend for this section to be normative; that is, we intend for it to define how questions are evaluated for inclusion both now and in the future. | ||
|
|
||
| Evaluating criteria: |
There was a problem hiding this comment.
These are great guidelines!
| - `> app` | ||
| - `addon` | ||
| - `Please provide the name of your app/addon:` | ||
| - `Please provide the spoken/content language of your app/addon: (use arrow keys)` |
There was a problem hiding this comment.
Have you considered the importance of the order of these questions? It seemed strange to me that the lang would be asked before package manager or CI. Maybe I have a preconceived notion that the options that are older/have been around longer should be first, or maybe how much code the question is responsible for changing, where package manager or CI would have more impact.
There was a problem hiding this comment.
@kellyselden having a way to determine the order of the questions asked is a good idea.
| - the default would be `en-US` | ||
| - if your system has a different language set (which can be confirmed by using the `echo $LANG` command in the terminal), then _that_ language would be shown as the second option | ||
| - if your system was already set to the default language, the second option would not be shown. | ||
| - for "manually define a language", we will validate the response against the allowed language codes |
There was a problem hiding this comment.
Should we be responsible for this? I relate this to something like timezones, it's really hard to get right. Are we sure we wouldn't be excluding anyone, like maybe an obsure or brand new code is introduced that we don't support? I'm don't know how static the list is.
There was a problem hiding this comment.
@kellyselden we're already doing this with the --lang flag. You're right that it could be a tricky issue but we have a fairly high level of confidence in the library that we're using for this. (is-language-code).
Are we sure we wouldn't be excluding anyone, like maybe an obscure or brand code is introduced that we don't support?
While new regions can be created (due to things like changes in political landscape), it's unlikely that there will be a new language code. All languages have codes, and even languages that no longer have living native speakers still have language codes. For example, xht is the code for the Hattic language, a historical language from 4,000 years ago.
There was a problem hiding this comment.
I'm not so sure about this. There is a page on Wikipedia about this, but it may not be up to date: https://en.wikipedia.org/wiki/Category:Languages_without_ISO_639-3_code
However, using a continually updated library is probably good enough since you can always edit index.html afterward.
There was a problem hiding this comment.
Here is my earlier written thoughts @MelSumner asked me prior to this RFC, which I thankfully was happy to share:
In my history of creating CLI tools that generate stuff I found followed these principles:
- A CLI command must be fully executable by typing it in
- If optional parameters aren't provided a default will be applied
- If there are missing required parameters a wizard kicks in to ask for required information instead of failing with an error message (unless you pass in something like
--no-interactive)- The wizard starts picking up questions from where-on information is missing.
That makes the wizard data sensitive and will not ask questions for which you passed in information already. By that makes the wizard scalable from asking the whole journey to only the fragile, missing parts and as a result a super enjoyable experience for the all sorts of types of developers.
I want to share some learnings from working on ember-cli-create:
- The first wizard contained questions like "do you want to have the welcome included"? That felt super awkward after a bit of time and super annoying. You want that welcome screen once or twice and then basically never again. Same for questions like yarn, etc. they didn't made sense.
- Having the CLI "UI" rather focussed on the things people want to achieve rather than putting a wizard around the possible parameters is +100 helpful
- E.g. ember-cli-create detected if you are in a workspace and if so applied
-sg
- E.g. ember-cli-create detected if you are in a workspace and if so applied
- It made no sense to distinguish between apps and addons. It was better to think about ember projects: app, addon, engine, glimmer, glimmer-webcomponent
- There are questions that depend on that type you select here first. E.g. picking the language is only related to an
app. Selecting the ci will work for all those projects.
That's why the first question of ec-create was asking what you wanted to do. Each answer had the type of project included and based on that compiled the follow-up questions. I think this is overall the better approach. I re-read the source of ec-create: It really has only one mandatory parameter which is the name for the project (not even what project, only the name). Second is the preset (the first question) asking for the what. There were some predefined (app, beginner, addon, glimmer, glimmer-wc + octane back in the day). The idea here is that a preset is more flexible than selecting the type of project. As the preset could contain more information than only the type of the project but also a pre-selection of preconfigured dependencies to install. Could also be the individual parameters, such as --yarn, --no-welcome, --lang, --ci that could be handled by that (and the blueprint). I guess my rough understanding was, that preset work with in front of blueprints. Well I'm drifting away from the original idea (or maybe not?). I always find it more pleasent to design something where you not only know the boundaries, but a large area around that to properly set the bounds.
I'm also sure I forget a lot of things to share here but I guess it is enough to start the discussion and the fine-tune from here.
|
|
||
| As part of the effort to make new Ember apps more conformant for digital accessibility requirements at a global scale, this RFC proposes an interactive workflow for new Ember apps. This will also have the benefit of assisting new users who prefer an interactive model of new app creation. | ||
|
|
||
| ## Motivation |
There was a problem hiding this comment.
The whole motivation section reads as if this is all justified through accessiblity, with one line at the end stating another position. While I agree and be super-happy about all additions, justifiying everything through it seems wrong to me. I would've rather read this as accessibility to be a motiviation and then background/reason/further explanation as an appendix.
I must say I'm heavily biased here, because I did this already, so I gonna share my motives as well in hope to see this coming all together nicely.
-
My main motive was to DX/UX in discoverability/assistance of the parameters passed to ember-cli -> recognition over recall.
-
Second motive was to address different types of developers. Some prefer command line, others prefer UIs instead. The idea here was to not only serve cli developers but also more UI happy users.
-
Third is to prevent execution errors of the command at hand. What happens when you type
ember new?❯ ember new The `ember new` command requires a name to be specified. For more details, use `ember help`.By adding nothing the command breaks. The motive was the dev is able to write the command he intends it to and not accidentaly having some default put on he/she doesn't want (you can think of this as linting 😀).
-
Better control over where your project is about to be created. Given ember-cli was created before there were scopes for npm packages, the name of the project to be the folder name for it is a good practice. When being in a workspace, in an already scoped folder creating a new package, this isn't a nice way to use the cli here. That is why
ember-cli-createwill always ask you for the folder, hitting enter will keep the default as is. -
Better workspace support:
ember-cli-createdetects whether you are in a workspace and executes ember cli with--skit-npmand--skip-git(which if you don't pass while in a workspace will be run).
I truly didn't had a11y on my mind back then but happy to see all this. Which brings me to the point how we make sure the CLI wizard is accessible? We are all adance our learning how to do this on websites but on CLI level? I have no idea!
There was a problem hiding this comment.
The whole motivation section reads as if this is all justified through accessibility
That's correct. It was the motivation for the work represented in this RFC, even if it has other benefits.
There was a problem hiding this comment.
It was the motivation for the work represented in this RFC, even if it has other benefits.
Hmm, I think this is slightly the wrong framing. I think it is perfect that the reason y'all looked into it was accessibility to begin with, but framing the "reason for the feature" as an accessibility one seems flat out wrong. I agree with @gossi here that the motiviation should be refactored a bit to make it clear that DX/UX is the primary factor (and that that is why it meets the accessibility goals as well!).
|
|
||
| ## Detailed design | ||
|
|
||
| ### Prior Art |
There was a problem hiding this comment.
For ember-cli-create I looked into vue-cli at that time (that was shortly before they release vue UI (or however they named it)).
| 1. Is it hard (or time-consuming) to change it later? *For example, it's easy to remove the `ember-welcome-page` addon, so we did not include it. But it's time consuming to change from `yarn` to `npm` (or vice-versa) so we made sure to include that.* | ||
| 1. Is it difficult to discover the option? | ||
| 1. What is the maintenance cost? *For example, a nice question to add could be something like, Do you want to use a CSS preprocessor? But, because Ember does not deal with SASS, LESS... by default, the interactive workflow will have to install an addon (like `ember-cli-less`) which would imply that the CLI team will have to ensure it never fails.* | ||
| 1. Does the question affect another one? *For example, the LTS question can affect the CI file generated by the CI question (setup tests on CI with `ember-try`). Questions that modify the result of other questions too much should be avoided to prevent high maintenance.* |
There was a problem hiding this comment.
I'm missing the evaluation of how it affects/bloats the UX/DX of it? It's hard to formulate my idea, let me give two example instead:
- Let's say we have a question to choose the
lang. We can skip the question if this is passed via--lang. - We can detect that we are in a workspace and if so, we will apply
--skip-npmand--skip-git
Maybe something along conditions under which a question is shown? Taking the environment into account and its impact on UX/DX.
phew - that's a hard one...
There was a problem hiding this comment.
Second thing I'm missing (also noted below) but I think it belongs here:
At which position is a question placed?
There is a couple of things taken into account. E.g. language can't be asked before known it is an app.
There was a problem hiding this comment.
The question order is based on a few things, but specifically, I wanted to ask the language question while the developers cognitive energy is still fresh. We've already decided that it won't matter if you're building an app or addon for this question, so it's position is fine for both.
There was a problem hiding this comment.
Third - How to take out questions?
This is a good question, and I will think about it and add something in here. Do you have anything specific that you'd want considered, @gossi ?
| - `> app` | ||
| - `addon` | ||
| - `Please provide the name of your app/addon:` | ||
| - `Please provide the spoken/content language of your app/addon: (use arrow keys)` |
There was a problem hiding this comment.
I love to surprise people, that bar is a valid language tag for bavarian. Not only would I voluntarily turn on voice over to listen to that - but it also doesn't follow the usually expected de-bar format.
That said: I love the idea to ask for the spoken/content language as the question hints for what this is used. Contrary, I would answer de to this (because this is my mother language) but the app I'm building might itself be in english. Also the options seem nice (I say seem, because this is what experience will show after release).
|
|
||
| If a user were to type in existing flags that are also questions in the interactive workflow (i.e., `ember new my-app --lang en-US --interactive`), it will skip the question entirely. | ||
|
|
||
| When a user types `ember new` into their command line, they will be asked these questions (defaults indicated by a `>`): |
There was a problem hiding this comment.
This section confuses me and I guess needs more explanation:
Above is stated the normative for picking question and this section? Are these examples? Is this the draft for the first iteration?
Some background how this document can be read/understood: the top section is hinting this RFC is finding a strategy for such question which is now made inconsistent by providing thm.
There was a problem hiding this comment.
The normative strategy for determining questions had two purposes:
- determine which of our questions on the draft list met the criteria for inclusion
- provide the framework for adding future questions
| - `Is this an app or an addon? (use arrow keys)` | ||
| - `> app` | ||
| - `addon` | ||
| - `Please provide the name of your app/addon:` |
There was a problem hiding this comment.
Next question:
- 'Where to create your project?:'
Default being the name of the project (from earlier), hitting enter will confirm that
There was a problem hiding this comment.
I think we want to assume that they are already in the right directory. Also it doesn't seem like something Ember wants to control, historically.
There was a problem hiding this comment.
Historically, there weren't npm scopes which changed the game. When I create the package @foo/bar I don't want to necessarily create it in that subbed folder - that was also one of the points to create ec-create.
| - `Pick the package manager to use when installing dependencies: (use arrow keys)` | ||
| - `> NPM` | ||
| - `Yarn` | ||
| - `ignore/skip` |
There was a problem hiding this comment.
'ignore/skip' shouldn't be here and rather be auto-detected. If so, hide this question completely.
There was a problem hiding this comment.
How do you think this can be auto-detected? Can you tell me more about that?
There was a problem hiding this comment.
It can be detected within workspaces for sure or when using lerna.
Dunno if I remember correctly but I think ember (once) offered me the option to set yarn as default, right? If so, this is also a resource to that.
|
|
||
| #### Package Manager | ||
|
|
||
| - ignore/skip has been added to cover the use case where the developer is in a workspace |
There was a problem hiding this comment.
see above, can be skipped completely when auto-detected.
|
|
||
| #### CI Option | ||
|
|
||
| Separate RFCs should further define more options for CI. |
There was a problem hiding this comment.
Also please take into consideration of auto-detection and a possible skip for such a question. Only if there is confidence in detection, anyway present highest probabilty as default.
| - `What is the earliest version of Ember that you intend to support? (use arrow keys)` | ||
| - `> recommended (last two LTS)` | ||
| - `last LTS` | ||
| - `manually define a version number` |
There was a problem hiding this comment.
From above:
What is the maintenance cost? For example, a nice question to add could be something like, Do you want to use a CSS preprocessor? But, because Ember does not deal with SASS, LESS... by default, the interactive workflow will have to install an addon (like
ember-cli-less) which would imply that the CLI team will have to ensure it never fails.
I can say, this is absolutely a nice idea but hardly manageable. A future possibility is to provide hooks for enhancing this by installing more addons (globally or per project). Vue cli did this with v2 already, was happy to see it when I was reading their code.
There was a problem hiding this comment.
What's the part that you think is not manageable? can you clarify what makes it not manageable? Thanks!
There was a problem hiding this comment.
Hard to manage a selection of possible options for addons to install. It's always subjective to the author(s) (if lectored) but I don't think will provide individuals/comapnies a good option. That's what I think, working on an API so you can customize it for yourself or your companies is hitting the mark - although I see this as a future addition, not even tomorrow but farther future
There was a problem hiding this comment.
It's impossible to accommodate to everyone's needs, but I'd say it's good idea to provide with an easily accessible set of commonly agreed useful options. I know that I want addons XY, because I'm comfortable with using them. In my company we know that we want AB, because that's what we've chosen.
But person that is new to the framework or even JS ecosystem in general will have no idea where to start. At that point being given hints that "you might want sass if you want flexible styles", "you might want eslint if you want linting", "you might want prettier if you want unified code formatter", etc. is a great help to get started.
In the future it might be a good idea to abstract this wizard functionality and let the users use external sets. But I would not over-engineer this at this point.
There was a problem hiding this comment.
@gossi Ahh yes, you were agreeing with the stated position then. We decided that it would be not manageable, which is why we didn't include it. 👍
There was a problem hiding this comment.
Yeah... Sometimes I speak in riddles. I'm pretty sure this question will arise sooner than later. I think ember shouldn't provide any answers here at all (as this would be prejudgement). Instead what I'm saying is - to reach there - it will be nice if ember would provide an API to hook into. That way people can install there own flavors (eg. yarn install -g ember-cli-new-config-css-modules) and then it will be picked up in the wizard, to give an idea. Truly the (over)next step.
| - if your system has a different language set (which can be confirmed by using the `echo $LANG` command in the terminal), then _that_ language would be shown as the second option | ||
| - if your system was already set to the default language, the second option would not be shown. | ||
| - for "manually define a language", we will validate the response against the allowed language codes | ||
| - we have not added a "skip" option here, because the purpose is to focus on improved accessibility in Ember apps. |
There was a problem hiding this comment.
what if I want to use ember-intl and then dont want a lang in the <html> tag of my index.html? Could we allow this as an option and install ember-intl? Or should ember-intl remove this during install? Or do we agree that there should always be a "default lang" in the index.html?
There was a problem hiding this comment.
ember-intl will update the lang attribute (adding it if it's not there). It's still a recommendation to set a default content/spoken app language, for a few reasons, one of which is that we're also adding linting support (via ember-template-lint) to check for it.
There was a problem hiding this comment.
This is addressing the case, when you are not using ember-intl and give the document a language.
|
|
||
| ## Summary | ||
|
|
||
| As part of the effort to make new Ember apps more conformant for digital accessibility requirements at a global scale, this RFC proposes an interactive workflow for new Ember apps. This will also have the benefit of assisting new users who prefer an interactive model of new app creation. |
There was a problem hiding this comment.
As part of the effort to make new Ember apps more conformant for digital accessibility requirements at a global scale, this RFC proposes an interactive workflow for new Ember apps.
How does an interactive app creation flow help "accessibility requirements at a global scale", what does it mean concretely?
What's the tax/cost for maintaining two flows for creating apps (interactive and non-interactive)? I don't know the answer to this, but someone on the ember-cli team should know. Do we want to take on this tax?
How does an interactive flow make things easier compared to a non-interactive, for a blind/deaf/etc person?
How does other terminal software, editors, etc. work? To effectively develop applications there are usually a ton of other tooling needed. Maybe these problems are better solved at a higher level of abstraction, i.e. at the editor, terminal and os level?
For other parts of Ember, we often contemplate whether a problem is best solved within the Ember project, or outside. For example, the upcoming changes to the build system (Embroider) is a lot about delegating asset pipeline stuff to other open-source projects in the JS ecosystem, instead of building everything ourselves.
There was a problem hiding this comment.
How does an interactive app creation flow help "accessibility requirements at a global scale", what does it mean concretely?
Agree with this critique of the wording. The interactive flow just makes it easier to use the new --lang option without remembering it exists, AFAICT that is the only way this relates to A11Y.
What's the tax/cost for maintaining two flows for creating apps (interactive and non-interactive)? I don't know the answer to this, but someone on the ember-cli team should know. Do we want to take on this tax?
The nice thing here is that everything here desugars into command line options that already exist. This means there isn't a duplicated cost of each option/etc, and the only new cost is the wizard / prompting itself. All of the underlying features are already implemented (or in the process of being implemented WRT to --lang) and tested.
From an ember-cli team perspective, I think this RFC is a very very large win for simplicity (both ember-cli's codebase, and ember-cli's users).
There was a problem hiding this comment.
That it desugars into existing (or future) command line options sounds good. Sort of like the .ember-cli file which afaik share much code with the CLI flags.
I don't know enough about ember-cli to determine whether the implementation cost is worth it. My point above was mainly to ask a few (uncomfortable) questions regarding prioritisation, and it's up to you on the core team to decide of course.
| 1. We could set the default language to US English (the default language of the Ember project) and not have an interactive option at all. | ||
|
|
||
| ## Unresolved questions | ||
| 1. Do we have a good way to make this a good experience for developers who use assistive technology? |
There was a problem hiding this comment.
How many Ember developers are using assistive technology? What problems do they have with Ember today?
If the underlying purpose here is to "reach" more developers? Are there other groups that are left out at the moment, for example developers that don't speak English very well? Perhaps translating the docs (or parts of them) to more languages would reach more developers?
There was a problem hiding this comment.
I don't know the total number but I am aware that there are some; after digging into this unresolved question a bit more, I am fairly confident that we can remove it. The answer is, "the terminal has to do most of the heavy lifting here" at least where development is concerned.
For the Ember team, providing clear error messages and ensuring that our guides and API docs are accessible will be the best support we can provide.
There was a problem hiding this comment.
Sounds reasonable, to solve most accessibility concerns on other levels than Ember. There are many interesting projects and great progress at the editor, terminal and os level. But I think these things are mostly better to address outside Ember.
If this RFC isn't mainly about accessibility though (sounds like it's more for first experience), maybe the motivation text in the RFC could be tweaked accordingly.
The underlying motivation for this RFC is the desire to improve the accessibility of new Ember apps as previously documented in Issue 595/Section 4. Specifically, it aims to prevent new Ember apps from failing legal requirements for accessibility conformance according to WCAG 2.1, the standard used by most countries around the world to inform digital accessibility requirements.
|
We discussed this in depth at todays core team meeting. There were a few tweaks / suggestions from the team that need to be taken care of, but the team is overwhelmingly in favor of moving this into final comment period once these tweaks are done:
Thanks for working on this @MelSumner! |
Updates to the motivation section of the RFC
There was a problem hiding this comment.
Thanks for those updates @MelSumner, this reads really well to me!
|
As mentioned in my last comment, now that we have those last few tweaks here we are moving this into final comment period. |
| - `manually define a version number` | ||
|
|
||
| ### Implementation | ||
| This section is not normative, but provided for extra context for folks who might be new to this idea in general. We could use something like [inquirer.js](https://github.com/SBoudrias/Inquirer.js) to implement this wizard, if the mechanism doesn't already exist within the ember-cli codebase. However, it should be explicitly noted that inquirer is only being used as an example of a library that could be used, and this RFC isn't explicitly defining that inquirer.js should be or will be used. |
There was a problem hiding this comment.
👍 - Absolutely! The idea that is conveyed here is that we will do prompting. Exactly how is an implementation detail in ember-cli (thats why the prose above says "we could use something like Inquirer.js").
|
Awesome work here y'all! Thanks for everyones time and effort to push this forward, let's do it!!!!! |
|
Took a stab: ember-cli/ember-cli#9824. |
This RFC introduces an interactive way to create a new Ember app.
Rendered