- Start Date: (fill me in with today's date, YYYY-MM-DD)
- Relevant Team(s): (fill this in with the team(s) to which this RFC applies)
- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name)
- Tracking: (leave this empty)
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.
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.
In that context, this RFC seeks to help new Ember applications achieve WCAG Success Criteria 3.1.1: language of page by providing users of ember-cli to specify the base human language of their new application within an interactive setup workflow.
This RFC is the result of analysis and discussion in Ember's accessibility strike team. The overall roadmap for addressing this issue is with a series of RFCs that intend to (independently) offer:
- a partial resolution to ensuring new Ember apps achieve WCAG Success Criteria 3.1.1 (language of the page)
- enhancements to Ember CLI that empower developers to make their applications more accessible-by-default
- global improvements to new Ember applications (i.e., improvements gained by achieving WCAG SC-3.1.1 that aren't specifically related to digital accessibility)
The first step of the solution was presented in RFC 635-- the addition of the --lang flag as a way to add the language attribute to the <html> tag in the index.html file of new Ember apps. As such, successful implementation of RFC 635 (or similar) is a necessary pre-requisite for this RFC, which in turn proposes an interactive workflow that can be initiated in the CLI when creating a new Ember app. With this in mind, this RFC will endeavor to not repeat the information in that RFC, but rather build on it, and reference when appropriate. The intention of RFC 635 was to provide the appropriate underlying mechanism for setting the page language to align new Ember apps with WCAG Success Criteria 3.1.1 (language of the page); the interactive workflow proposed in this RFC intends to harness that mechanism.
Lastly, this RFC is equally motivated by providing 'global' application improvements to the ember new workflow. Briefly, these improvements can be summarized as:
- improvements to applications caused by achieving WCAG SC-3.1.1 that aren't strictly accessibility-related (as outlined in RFC 635)
- flattening the learning curve for new users by providing them with an interactive environment and helpful feedback during troubleshooting, error handling, etc.
When considering what questions to ask, we considered a few things:
- What questions do we have to ask ourselves every time we create a new Ember app?
- How many questions do we think developers will tolerate?
- Should the questions be different if it is an app vs addon?
We are purposefully limiting the questions that this interactive workflow asks in this RFC; future questions may be introduced through separate RFCs but it is not the intent of the Accessibility strike team to do so (at this time).
We will also endeavor to provide strong defaults for these questions, based on the results from the community surveys we have been conducting over the past few years and the defaults as stated by Ember itself (either explicitly or implicitly). If these defaults change over time as the result of community RFCs, the default values or other responses for the interactive questions should be updated as part of those RFCs.
How do we decide what becomes a question in the interactive workflow? Here are the questions we can use to help us decide this:
- 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.
- Is it difficult to discover the option?
- What is the maintenance cost? For example, a nice question to add could be Do you want to use a CSS preprocessor? But, because ember does not deal with SASS, LESS... by default. The wizard will have to install an addon (like ember-cli-less) which implies that the CLI team will have to ensure it never fails.
- 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.
It would be remiss to introduce this RFC without mentioning the prior art that we have for wizard-like app creation. In the Ember community, @gossi first introduced this idea with ember-cli-create. In the wider web community, the Vue community offers this through vue create (see docs).
The following commands, and reasonable combinations thereof, should work to enter into the interactive workflow:
ember newember new --interactiveember new -iember new my-app -i
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.
When a user types ember new into their command line, they will be asked these questions (defaults indicated by a >):
Is this an app or an addon? (use arrow keys)> appaddon
Please provide the name of your app/addon:Please provide the spoken/content language of your app/addon: (use arrow keys)> en-USmy computer's default languagemanually define a different language
Pick the package manager to use when installing dependencies: (use arrow keys)> NPMYarnignore/skip
What CI system do you want to use? (use arrow keys)> travis-ciignore/skip
App/Addon Name There will be no default for this question. The user must enter a response.
App/Addon Language
- the default would be
en-US - if your system has a different language set (which can be confirmed by using the
echo $LANGcommand 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.
Package Manager
- ignore/skip has been added to cover the use case where the developer is in a workspace
CI Option RFCs should be further defined to include more options for CI.
Explicitly, the goal of this RFC is to only include ember-cli flags that already exist. Any other possibilities should be considered future work.
This interactive workflow will also ignore any ~/.ember-cli settings that already exist. A separate RFC should be written that makes it possible for these to things to co-exist and respect the settings of the other.
An example of a future RFC that could be specific to addons, would be to add a --supported-version flag for addons and add that to the wizard:
What is the earliest version of Ember that you intend to support? (use arrow keys)> recommended (last two LTS)last LTSmanually define a version number
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 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.
As this is a wholly new idea, it should be documented and added to the guides along with screenshots of the new workflow. Until that prototype exists, this section will largely remain empty. However, we intend to explain it similarly to Vue's documentation for a similar feature (https://cli.vuejs.org/guide/creating-a-project.html#vue-create).
It could be considered a drawback to make this not the default for new Ember apps, even if an app name is defined.
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.
- We could decide on a different list of questions. See the notes from the strike team discussion on May 20th to review the other possibilities considered.
- We could make this the default for new Ember apps and add it in 4.0 as a permanent change.
- We could have this workflow be opt-in only, via the
--interactiveflag (e.g.,ember new --interactive). Using theember newcommand would error and trigger the help workflow (which would be updated to include the--interactiveflag). - We could set the default language to US English (the default language of the Ember project) and remove the language question from the interactive workflow.
- Do we have a good way to make this a good experience for developers who use assistive technology?
As we identify additional unresolved questions, we will add them here.
In my history of creating CLI tools that generate stuff I found followed these principles:
--no-interactive)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:-sgapp. Selecting the ci will work for all those projects.That's why the first question of
ec-createwas 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 ofec-create: It really has only one mandatory parameter which is thenamefor 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,--cithat 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.