Update language text to specify language versions. #863
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Also make it explicit how experiments work and where Pub gets the default language version from. See issue #858.
eernstg
approved these changes
Mar 2, 2020
There was a problem hiding this comment.
LGTM, suggesting that we're adjusted a couple of occurrences of 'language' to 'language version' and introduce (explicitly) the notion of a 'language version number'. The effect is that we will consistently talk about each of the "different Darts over time" as a 'language version' that has a 'language version number', and we don't talk about them as "different languages".
Then when we get to --enable-experiment=... we switch to talk about 'experimental languages'. We could insist on saying 'version' in some way, but I don't think that's helpful. We avoid implying that there is a 'number' for an experimental language, and when it's explicitly introduced I think it's OK to talk about 'experimental languages' even though we avoid calling each 'language version' a 'language'.
| @@ -1,7 +1,7 @@ | |||
| # Dart Language Versioning | |||
|
|
|||
| [lrn@google.com](@lrhn)<br> | |||
| Version: 1.4<br> | |||
| Version: 1.5<br> | |||
| Status: Ready for implementation. | |||
There was a problem hiding this comment.
Wouldn't that be a few steps into the status 'implemented'?
|
|
||
| Then the Dart language tools must be able to handle libraries written for different language versions interacting in the same program. Most language changes are incremental and non-breaking. For those, all the tools have to do is to make sure that a library does not use a feature which was introduced after the library's language version. | ||
| Each new [version](https://semver.org/) of the Dart SDK since then has added more features to the Dart 2 language. Or more precisely, each one has introduced a *new language*. The language of the Dart 2.0.0 release is different from the one of the Dart 2.1.0 release because, for example, the latter language allows you to use integer literals in double contexts. A program written using that feature is not considered a valid Dart program by the Dart 2.0.0 SDK. |
There was a problem hiding this comment.
It is confusing that we talk each 'language version' being a new 'language', and then in the next section (line 39) to return and talk about a 'language version'.
I think it would be more readable to talk only about language versions in the main (upright) text, and then add a commentary section (like this) explaining that each language version is a new and separate language, because the same program may be accepted as being written in language version 2.1 whereas it would have compile-time errors when considered as a version 2.0 Dart program.
Having said that, every subsequent reference should say 'language version' rather than 'language' when we refer to differences between said language versions. At the same time, we refer to a given language version by stating the relevant 'language version number'.
|
|
||
| For breaking changes, the tool must be able to handle multiple different versions of the language, and do so in a way that allows libraries on different language versions to interact in a predictable and useful way. For example, the "non-nullable types by default" feature (NNBD) will have NNBD libraries with non-nullable or safely nullable types *and* unmigrated libraries with unsafely nullable types, and those libraries can send values back and forth between them. This is where the main complication lies, and that is beyond the scope of this document which only specifies how we assign language versions to individual libraries. | ||
| Each Dart SDK stable release has introduced a new *version* of the Dart language. We will denote those language versions by a *language version* which is the major and minor numbers of the Dart release which introduced the language. The language of the Dart 2.0.0 release is Dart 2.0 (language version 2.0), and the language of the most recent Dart release has language version 2.7. A language version is equivalent to a Semantic Versioning version with a patch version of `.0` and no `-` or `+` parts. |
There was a problem hiding this comment.
Can we omit the last sentence? It doesn't seem to contribute anything which is helpful. If we wish to say that a specific version of a tool serves as an indication that it implements a specific language version, then we could say that more explicitly:
"A Dart tool that reports a major version k, minor version m, and patch version 0 with no suffix (for instance, a suffix could be -dev.3.0) implements language version k.m."
Suggested change
| Each Dart SDK stable release has introduced a new *version* of the Dart language. We will denote those language versions by a *language version* which is the major and minor numbers of the Dart release which introduced the language. The language of the Dart 2.0.0 release is Dart 2.0 (language version 2.0), and the language of the most recent Dart release has language version 2.7. A language version is equivalent to a Semantic Versioning version with a patch version of `.0` and no `-` or `+` parts. | |
| Each Dart SDK stable release has introduced a new *version* of the Dart language. We will refer to those language versions by a *language version number* which is the major and minor numbers of the Dart release which introduced the language. The language version of the Dart 2.0.0 release is Dart 2.0 (language version number 2.0), and the language version of the most recent Dart release has language version number 2.7. | |
| A Dart tool that reports a major version number _k_, minor version number _m_, and patch version `0` with no suffix (for instance, a suffix could be `-dev.3.0`) implements the language version with number _k.m_. | |
| In the following, we will use the phrase *language version* to refer to the language as well as its number. |
|
|
||
| This feature cannot support language changes that are fundamentally incompatible with earlier language versions, we do need the run-time system to be able to contain both language versions at the same time. For the same reason, this feature does not handle *platform library* changes that are not backwards compatible. The libraries are shared between the different language version libraries in a program, and must work for all of these. (The tools should still detect use of library features not supported by the minimum required SDK version for a package.) | ||
| All significant Dart language changes happen in stable releases, which means a Dart release which increments the minor or major version number of the SDK version number. At time of writing, the most recent release is version 2.7.1, and the next might be 2.8.0 (or 2.10.0 if we decide to skip some versions). |
There was a problem hiding this comment.
Suggested change
| All significant Dart language changes happen in stable releases, which means a Dart release which increments the minor or major version number of the SDK version number. At time of writing, the most recent release is version 2.7.1, and the next might be 2.8.0 (or 2.10.0 if we decide to skip some versions). | |
| All significant Dart language changes happen in stable releases, which means that a Dart release which increments the minor or major version number of the SDK version number. At time of writing, the most recent release is version 2.7.1, and the next might be 2.8.0 (or 2.10.0 if we decide to skip some versions). |
|
|
||
| When we develop new language features under an experimental flag, that flag only enables the new features for libraries that are already using the most recent SDK language version. An experimental feature cannot be used by a library which is stuck on a lower language version. This should make complicated interaction between new features and old syntax easier to avoid, and new features are entirely incremental. | ||
| Each library in a Dart program will have precisely one associated *language version* which defines the language syntax and semantics which are applied to that library. This document specifies how to assign a language version to libraries. This is perhaps the least of the technical problems inherent in having libraries with multiple language versions running in the same program, but it is the basis that the remaining solutions are build on. |
There was a problem hiding this comment.
Suggested change
| Each library in a Dart program will have precisely one associated *language version* which defines the language syntax and semantics which are applied to that library. This document specifies how to assign a language version to libraries. This is perhaps the least of the technical problems inherent in having libraries with multiple language versions running in the same program, but it is the basis that the remaining solutions are build on. | |
| Each library in a Dart program will have precisely one associated language version which defines the language syntax and semantics which are applied to that library. This document specifies how to assign a language version to libraries. This is perhaps the least of the technical problems inherent in having libraries with multiple language versions running in the same program, but it is the basis that the remaining solutions are built on. |
I removed the *...* around language version because this is not the defining occurrence of that phrase.
|
|
||
| The actual language of the next Dart release is not known for certain until that Dart SDK is finally released. All new features currently being developed are experimental and subject to being changed, postponed, or withdrawn. | ||
|
|
||
| During the development of a next Dart release, the SDK exists only as developer releases (for example, the Dart SDK version on bleeding edge is 2.8.0-dev.9.0). There is no Dart 2.8 language yet, but there is a family of experimental Dart 2.8 languages that users can experiment with. |
There was a problem hiding this comment.
Suggested change
| During the development of a next Dart release, the SDK exists only as developer releases (for example, the Dart SDK version on bleeding edge is 2.8.0-dev.9.0). There is no Dart 2.8 language yet, but there is a family of experimental Dart 2.8 languages that users can experiment with. | |
| During the development of a next Dart release, the SDK exists only as developer releases (for example, the Dart SDK version on bleeding edge is 2.8.0-dev.9.0). There is no Dart 2.8 language version yet, but there is a family of experimental Dart 2.8 languages that users can experiment with. |
It makes sense to introduce those 'experimental Dart 2.8 languages', and it would be confusing to insist that they are 'versions' of the language. Keeping them separate enables us to always have an associated version number whenever we have a language version.
|
|
||
| During the development of a next Dart release, the SDK exists only as developer releases (for example, the Dart SDK version on bleeding edge is 2.8.0-dev.9.0). There is no Dart 2.8 language yet, but there is a family of experimental Dart 2.8 languages that users can experiment with. | ||
|
|
||
| We switch between these language versions using the `–enable-experiment` flag to the Dart compilers and other tools. The current *base* Dart 2.8 language, the one used with no experiments enabled, is the same as the 2.7 language. A different 2.8 language can be used by enabling one or more experiments. There are, at time of writing, four experiments in various degrees of completion: |
There was a problem hiding this comment.
Suggested change
| We switch between these language versions using the `–enable-experiment` flag to the Dart compilers and other tools. The current *base* Dart 2.8 language, the one used with no experiments enabled, is the same as the 2.7 language. A different 2.8 language can be used by enabling one or more experiments. There are, at time of writing, four experiments in various degrees of completion: | |
| We switch between these experimental languages using the `–enable-experiment` flag to the Dart compilers and other tools. The current *base* language for experiments under version 2.8, the one used with no experiments enabled, is the same as language version 2.7. A different 2.8 experimental language can be used by enabling one or more experiments. There are, at time of writing, four experiments in various degrees of completion: |
|
|
||
| Example package entry: | ||
| The package configuration file, `.dart_tool/package_config.json`, file is a JSON formatted text file which defines the configuration for a number of named packages using entries of the form: |
There was a problem hiding this comment.
Whitespace:
Suggested change
| The package configuration file, `.dart_tool/package_config.json`, file is a JSON formatted text file which defines the configuration for a number of named packages using entries of the form: | |
| The package configuration file, `.dart_tool/package_config.json`, file is a JSON formatted text file which defines the configuration for a number of named packages using entries of the form: |
|
|
||
| This means that all Dart libraries in, e.g., `test/` and `bin/` directories of a Pub package are considered as belonging to the package, not just the libraries accessed using `package:` URIs. | ||
| Tools will not have a language default version available for any package until a `package_config.json` file has been generated by running `pub get`. Any tool able to understand Pub package layout *may* derive the information directly from the `pubspec.yaml` of the current package, rather than rely on an entry in the `package_config.json` file, as long as it derives the same values that Pub would have written into the `package_config.json` file. A lack of a `package_config.json` file is only an issue for *new* packages, or packages with no dependencies, because otherwise the package is mostly unusable until you run `pub get` anyway. A new package is likely to want to be run at the most recent language version, so this is not a major problem. An IDE which reruns `pub get` after each change to `pubspec.yaml` will keep the `package_config.json` file up-to-date. |
There was a problem hiding this comment.
Whitespace:
Suggested change
| Tools will not have a language default version available for any package until a `package_config.json` file has been generated by running `pub get`. Any tool able to understand Pub package layout *may* derive the information directly from the `pubspec.yaml` of the current package, rather than rely on an entry in the `package_config.json` file, as long as it derives the same values that Pub would have written into the `package_config.json` file. A lack of a `package_config.json` file is only an issue for *new* packages, or packages with no dependencies, because otherwise the package is mostly unusable until you run `pub get` anyway. A new package is likely to want to be run at the most recent language version, so this is not a major problem. An IDE which reruns `pub get` after each change to `pubspec.yaml` will keep the `package_config.json` file up-to-date. | |
| Tools will not have a language default version available for any package until a `package_config.json` file has been generated by running `pub get`. Any tool able to understand Pub package layout *may* derive the information directly from the `pubspec.yaml` of the current package, rather than rely on an entry in the `package_config.json` file, as long as it derives the same values that Pub would have written into the `package_config.json` file. A lack of a `package_config.json` file is only an issue for *new* packages, or packages with no dependencies, because otherwise the package is mostly unusable until you run `pub get` anyway. A new package is likely to want to be run at the most recent language version, so this is not a major problem. An IDE which reruns `pub get` after each change to `pubspec.yaml` will keep the `package_config.json` file up-to-date. |
| 1.5: Rewrite and elaboration: | ||
|
|
||
| - Make it explicit how the Pub tool choses the package default language version |
There was a problem hiding this comment.
Suggested change
| - Make it explicit how the Pub tool choses the package default language version | |
| - Make it explicit how the Pub tool choses the package default language version. |
|
@lrhn can this be closed? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Also make it explicit how experiments work and where Pub gets the default language version from.
See issue #858.