Merge remote-tracking branch 'github/master'
Close unpaired opening parenthese and fix mispelling (#30406) Create experimental flags documentation (#34921) * Create experimental-flags.md * 80 cols * Review feedback from Devon * Update experimental-flags.md * Remove short form (-e) Change-Id: I808296c4517e621ba21520bb94cb9b9778e6fd1e Reviewed-on: https://dart-review.googlesource.com/c/82582 Reviewed-by: Michael Thomsen <mit@google.com>
This commit is contained in:
Jonas Termansen
@@ -0,0 +1,97 @@
|
||||
# Dart SDK process for changes behind experimental flags
|
||||
|
||||
## Problem statement
|
||||
|
||||
The Dart SDK ships via a number of channels:
|
||||
|
||||
- Via the [Dart SDK](https://www.dartlang.org/tools/sdk#install)
|
||||
- Via the [Flutter SDK](http://flutter.io)
|
||||
- Internally at Google via an internal channel
|
||||
|
||||
Each of these channels use varying release calendars, and keeping these entirely
|
||||
aligned is not practical. Further, a number of developers interested in staying
|
||||
current with Dart changes, consume the Dart SDK via our [dev
|
||||
channel](https://github.com/dart-lang/sdk/wiki/Branches-and-releases). As a
|
||||
result, we should anticipate that any dev channel build has the potential to end
|
||||
up as a shipped SDK though some channel. And as a consequence of that, it is
|
||||
critical that we keep the quality of our dev channel high AND that we keep it
|
||||
consistent wrt. which features are complete and supported. At the same time, we
|
||||
need the ability to land incomplete features to facilitate a number of tasks:
|
||||
|
||||
- Compose a feature that spans multiple components/areas
|
||||
- Automated testing prior to the full completion of the feature
|
||||
- Allow partner teams to get a preview of a future feature
|
||||
- Allow customers to get a preview of a future feature
|
||||
- Etc.
|
||||
|
||||
## Solution
|
||||
|
||||
To ensure completed & supported features can be differentiated from incomplete
|
||||
features in-progress, we will put all in-progress features behind a single set
|
||||
of flags. Changes to features behind these flags are not considered breaking
|
||||
(even if the feature behind the flag was in a stable SDK), and they are subject
|
||||
to removal at any time. For details about breaking changes, see the breaking
|
||||
change process.
|
||||
|
||||
All new features that meet one of the following criteria must be developed
|
||||
behind a flag (when possible):
|
||||
|
||||
- All breaking changes
|
||||
- All language changes
|
||||
|
||||
Further, it is recommended to consider developing behind a flag when:
|
||||
|
||||
- Landing larger, user-visible changes which will be in an intermediate state
|
||||
over several weeks and perhaps even releases
|
||||
- Making changes with the potential to have significant negative performance
|
||||
impact for several weeks and perhaps even across releases
|
||||
|
||||
## Details
|
||||
|
||||
### Flag format for CLI-based tools
|
||||
|
||||
Flags consist of one or more words, combined using dashes, using all lower-case.
|
||||
The single source of truth of these flags shall be a single shared .dart file.
|
||||
The tools are expected to offer a framework for querying these flags so that the
|
||||
implementation of the tools can easily access new flags.
|
||||
|
||||
The flags are passed to CLI-based tools using the `--enable-experiment` flag
|
||||
Multiple flags can be passed by using multiple flags, or by passing several
|
||||
comma-separated flags. Examples:
|
||||
|
||||
```
|
||||
dart --enable-experiment super-mixins
|
||||
dart --enable-experiment super-mixins,no-slow-checks,preview-dart3
|
||||
dart --enable-experiment super-mixins --enable-experiment no-slow-checks --enable-experiment preview-dart3
|
||||
```
|
||||
|
||||
If the user passes a flag that is not recognized (for example, when the flag is
|
||||
no longer supported), the tool is required to inform about this by printing to
|
||||
stderr, and not fail.
|
||||
|
||||
```
|
||||
dart --enable-experiment better-mixins
|
||||
Unknown experiment flag 'better-mixins'.
|
||||
```
|
||||
|
||||
### Flag format for UI-based tools (IDEs/editors/etc.)
|
||||
|
||||
IDEs and editors which offer the ability to invoke Dart tools, must support
|
||||
passing these flags. The support should be generic and flexible so that no UI
|
||||
change is required when we add or remove a flag. This is expected to take one of
|
||||
two forms:
|
||||
|
||||
- Experiments affecting analysis can be enabled in `analysis_options.yaml` under
|
||||
a single `enable-experiment:` key, e.g. to enable the flags `super-mixins` &
|
||||
`no-slow-checks`:
|
||||
|
||||
```
|
||||
analyzer:
|
||||
enable-experiment:
|
||||
- super-mixins
|
||||
- no-slow-checks
|
||||
```
|
||||
|
||||
- Experiments affecting launch/run behavior, can be enabled in the IDE specific
|
||||
run Configuration, by passing the same `--enable-experiment` flag as listed in
|
||||
the CLI section.
|
||||
@@ -3,7 +3,7 @@ dev_compiler
|
||||
|
||||
[](https://travis-ci.org/dart-lang/sdk)
|
||||
|
||||
The Dart Dev Compiler (DDC) is a fast, modular compiler that generates modern JavaScript (EcmaScript 6). Its primary use today is to support fast, iterative development of Dart web applications for Chrome and other modern browers.
|
||||
The Dart Dev Compiler (DDC) is a fast, modular compiler that generates modern JavaScript (EcmaScript 6). Its primary use today is to support fast, iterative development of Dart web applications for Chrome and other modern browsers.
|
||||
|
||||
Most users will use DDC via [pub](https://webdev.dartlang.org/tools/pub/pub-serve). It is supported by pub starting with the Dart 1.24 release.
|
||||
|
||||
@@ -32,12 +32,12 @@ See the [strong mode documentation](STRONG_MODE.md) for more details.
|
||||
|
||||
# Modularity
|
||||
|
||||
DDC provides fast, incremental compilation based on standard JavaScript modules. Unlike Dart2JS, DDC does not require an entire Dart application. Instead, it operates modularly: it compiles a set of Dart files into a JavaScript module. A DDC compilation step requires a set of input Dart files and a set of *summaries* of dependencies. It performs modular type checking as part of this compilation step, and, if the input type checks, it generates a JavaScript module (e.g., [*ES6*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import), [*AMD*](https://github.com/amdjs/amdjs-api/blob/master/AMD.md), or [*CommonJS*](https://nodejs.org/docs/latest/api/modules.html). The browser (i.e., the JavaScript runtime) loads and links the generated modules when running the application.
|
||||
During development, a compilation step only needs to be rerun if the Dart files or summaries it relies upon change. For most changes, only a very small part of your code will require recompilation. Morever, modules that are unchanged can be cached in the browser.
|
||||
DDC provides fast, incremental compilation based on standard JavaScript modules. Unlike Dart2JS, DDC does not require an entire Dart application. Instead, it operates modularly: it compiles a set of Dart files into a JavaScript module. A DDC compilation step requires a set of input Dart files and a set of *summaries* of dependencies. It performs modular type checking as part of this compilation step, and, if the input type checks, it generates a JavaScript module (e.g., [*ES6*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import), [*AMD*](https://github.com/amdjs/amdjs-api/blob/master/AMD.md), or [*CommonJS*](https://nodejs.org/docs/latest/api/modules.html)). The browser (i.e., the JavaScript runtime) loads and links the generated modules when running the application.
|
||||
During development, a compilation step only needs to be rerun if the Dart files or summaries it relies upon change. For most changes, only a very small part of your code will require recompilation. Moreover, modules that are unchanged can be cached in the browser.
|
||||
|
||||
Most users invoke DDC indirectly via [pub](https://webdev.dartlang.org/tools/pub/pub-serve). Pub computes module structure and build steps automatically and invoke DDC accordingly. Pub configures DDC to use AMD modules and uses the standard [AMD `require.js` loader](http://requirejs.org/) to bootstrap and load the application.
|
||||
|
||||
More advanced users may want to configure or invoke DDC directly. In general, the mapping of Dart files to JS modules is flexible. The key requirement is that module dependences (i.e., `require` in AMD or CommonJS or `import` in ES6) must be acyclic. In practice, this means that individual Dart libraries cannot each be mapped to a corresponding JS module (as Dart imports can be and often are cyclic). See the [usage document](USAGE.md) for more details.
|
||||
More advanced users may want to configure or invoke DDC directly. In general, the mapping of Dart files to JS modules is flexible. The key requirement is that module dependencies (i.e., `require` in AMD or CommonJS or `import` in ES6) must be acyclic. In practice, this means that individual Dart libraries cannot each be mapped to a corresponding JS module (as Dart imports can be and often are cyclic). See the [usage document](USAGE.md) for more details.
|
||||
|
||||
# EcmaScript 6
|
||||
|
||||
|
||||
Reference in New Issue
Block a user