From db60b840c2f04a31c14103de770e340182eedb09 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 28 Oct 2024 22:10:20 +0000 Subject: [PATCH 1/4] Update the lifecycle of a language feature documentation. --- doc/life_of_a_language_feature.md | 278 -------------------- doc/lifecycle_of_a_language_feature.md | 347 +++++++++++++++++++++++++ 2 files changed, 347 insertions(+), 278 deletions(-) delete mode 100644 doc/life_of_a_language_feature.md create mode 100644 doc/lifecycle_of_a_language_feature.md diff --git a/doc/life_of_a_language_feature.md b/doc/life_of_a_language_feature.md deleted file mode 100644 index 06d6f64bc..000000000 --- a/doc/life_of_a_language_feature.md +++ /dev/null @@ -1,278 +0,0 @@ -# Dart language evolution process - -## User issue or feature request - -Features and changes arise from perceived user issues or feature requests. -Feature requests should be filed in the [language -repo](https://github.com/dart-lang/language/issues/new?labels=request), and are -labelled [`request`](https://github.com/dart-lang/language/labels/request). -We may close issues that we believe that we will not -address for whatever reason, or we may keep issues open indefinitely if we -believe they are something that we may wish to address in the future. Feature -request issues are primarily for documentation of the user issue to be solved. - -## Design, feedback, and iteration - -When a member of the language team decides to take up an issue, we will create a -specific "language feature" issue (labelled [`feature`](https://github.com/dart-lang/language/labels/feature)) -for tracking the solution to the user issue/problem or feature under consideration. - -Interested parties may propose several (competing) language features to a -single request/problem. Such a proposal consist of: - -- A issue labelled 'feature' for discussion of a proposed solution - -- A link to an initial writeup of the proposed solution. This writeup should be -checked into a sub-directory with the name of the feature (`/[feature-name]/`), -located inside the -[`working`](https://github.com/dart-lang/language/tree/master/working) -directory of the language repository. The filename should be `feature-specification.md`. - -Additional materials may be added along side the writeup. - -All written plans, specs, and materials must be written using [GitHub flavored -Markdown format](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) -format, and must use the `.md` extension. - -Proposals may be iterated on in-place. - -As mentioned, alternative proposals should have their own issue and writeup. - -All proposals should be linked from and link to the 'request' for -the user problem/feature request they are trying to address. - -For smaller and non-controversial features, we will sometimes skip this step and -proceed directly to the [Acceptance and -implementation](#acceptance-and-implementation) phase. - -### External (outside of the language team) feedback - -We expect to use the github issue tracker as the primary place for accepting -feedback on proposals, solicited or unsolicited. If we solicit feedback, we -anticipate opening an issue for discussion and feedback, but also encouraging -filing and splitting off different issues for different threads of discussion. - -We generally expect to formally solicit at least one round of feedback on -significant changes. - -## Acceptance and implementation - -If consensus is reached on a specific proposal and we decide to accept it, a -member of the language team will be chosen to shepherd the implementation. -The implementation will be tracked via two artifacts: - - - A feature specification document - - - A 'implementation' issue. - -The 'feature specification' is **a single canonical writeup of the language -feature** which is to serve as the implementation reference. Feature -specifications use Markdown format. The file name should be -`feature-specification.md`, and the feature specification should be located -inside the `accepted/future-releases/` folder. - -The implementation issue (labelled `implementation`) will be filed in the -language repository for tracking the implementation process. This top of this -issue must contain links to: - - - The related `request` and `feature` issues (if they exist) - - - A link to the feature specification - -### Kick-off meetings - -The next step of the implementation issue is to get sign-off from all of the -relevant implementation teams indicating that they understand the proposal, -believe that it can reasonably be implemented, and feel that they have -sufficient details to proceed. - -Consider getting sign-off from the following teams: - -- The analyzer team. - -- The CFE team. - -- Back-end teams: - - - Dart native runtime - - - Dart for web - - - Wasm - -Note that if a feature consists entirely of a new piece of syntactic sugar, it -can be tempting to assume that it's not necessary to consult with any back-end -teams (since the CFE will lower the new syntax into a kernel form that is -already supported). But this can be a dangerous assumption. It's easy to forget -that even in features that appear to consist purely of syntactic sugar, some -back-end support may be needed in order to properly support single-step -debugging or hot reload. Also, some work may need to be done on back-end code -generators in order to make sure that the new feature is lowered into a form -that can be well optimized. To avoid missing things, we prefer to err on the -side of asking teams whether they're affected, rather than assuming they won't -be. - -Since feature specification documents are usually long and very detailed, we -like to begin this sign-off process with a set of kick-off meetings, typically -one for each affected implementation team. These meetings are on opportunity for -a language team representative to present a broad outline of the new feature, -give some concrete examples, and collect insights from the implementation teams -about what aspects of the implementation might need special attention. - -There may be further iteration on the proposal -in this phase. This sign-off must be recorded in the implementation issue. -Changes will be done in place on the writeup. - -### Implementation issues - -A typical outcome of the kick-off meetings will be a set of implementaiton -issues in the SDK repo, to track specific pieces of work that need to be -done. - -Additionally, Kevin Chisholm has a script for generating the core set of -implementation issues for a feature: -https://github.com/itsjustkevin/flutter_release_scripts/blob/main/languageFeatures.js. We -like to use this script for larger features. It creates a large number of -issues, though, so we will sometimes skip it for smaller features that only -require a small amount of work. - -Some teams have checklists that they consult when creating implementation -issues, to make sure important areas of work aren't forgotten. For example: - -- [Implementing a new language feature - (analyzer)](https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/doc/process/new_language_feature.md) - -- [Implementing a new language feature (analysis - server)](https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server/doc/process/new_language_feature.md) - -### Feature flag - -Most new language features should be implemented using a feature flag. The -feature flag serves several purposes: - -- It allows the feature to be implemented over a series of CLs without - destabilizing the SDK. If it comes time to ship a new release of the SDK - before the feature is ready, the feature flag can remain off, so users won't - be exposed to a partially-implemented or buggy feature before it's ready. - -- It allows users to opt in to trying out features that have not yet been - released, by turning on the feature flag locally. - -- Once the feature is enabled, the feature flag logic ensures that it will only - affect users who have set their language version to a version that includes - the new feature. This is especially important for package developers who may - want to support a range of versions of the Dart SDK. - -Note that implementing a language feature using a feature flag is frequently -more work that implementing it without a feature flag, since the compiler and -analyzer must faithfully implement both the old and new behaviors. Occasionally -the language team may decide that the benefits of using a feature flag don't -justify this extra work. But this is a rare senario. If you are working on a -feature and believe you don't need to use a feature flag, please consult with -the language team to be sure. - -Creating the feature flag should be one of the first implementation -tasks. Here's how to do it: - -- Add an entry to `tools/experimental_features.yaml` describing the feature, in - the top section (above the line that says `Flags below this line are - shipped`). - -- Run `dart pkg/front_end/tool/fasta.dart generate-experimental-flags` to update - `pkg/_fe_analyzer_shared/lib/src/experiments/flags.dart` and - `pkg/front_end/lib/src/api_prototype/experimental_flags_generated.dart`. - -- Run `dart pkg/analyzer/tool/experiments/generate.dart` to update - `pkg/analyzer/lib/src/dart/analysis/experiments.g.dart`. - -- Add a static final declaration to the `Feature` class in - `pkg/analyzer/lib/dart/analysis/features.dart`. - -- Increment the value of `AnalysisDriver.DATA_VERSION` in - `pkg/analyzer/lib/src/dart/analysis/driver.dart`. - -- Example CL: https://dart-review.googlesource.com/c/sdk/+/365545 - -### Language testing - -The language team will generally write a preliminary set of language tests for a -feature, in the SDK's `tests/language` subdirectory. These tests are not -intended to be exhaustive, but should illustrate and exercise important and -non-obvious features. Implementation teams are encouraged to write additional -language or unit tests. The language team may also coordinate the writing of -additional tests. - -An important use case for any new language feature is to ensure that the feature -isn't accidentally used by package authors that have not yet opted into a -language version that supports it. So in addition to testing that the new -language feature works when the feature flag is turned on, the tests added to -`tests/language` should verify that when the feature flag is turned off, the -previous behavior of the SDK is preserved. - -One important exception to preserving previous SDK behavior is that it's -permissible (and even encouraged) to improve error messages so that if the user -tries to use a disabled language feature, they receive an error explaining that -they need to enable it, rather than, say, a confusing set of parse errors. - -To enable the feature in a language test, include the line `// -SharedOptions=--enable-experiment=$FEATURE` near the top of the test (before the -first directive), where `$FEATURE` is replaced with the feature name. To disable -the feature in a language test, include the line `// @dart=$VERSION` near the -top of the test (before the first directive), where `$VERSION` is the current -stable release of Dart (and therefore is the largest version that is guaranteed -_not_ to contain the feature). - -### Google3 testing - -New features should be tested in Google's internal code base before they are -switched on. - -Details of how to do this will be described in a separate (Google internal) -document. - -## Shipping - -Implemented features will be released according to the implementation plan. -The language team will contribute to: - - - Helping internal and external teams through any required migration. - - - Communicating and advertising the change. - - - Documenting the change. - - - Releasing the change. - -## After shipping - -After a feature has been shipped, the documents pertaining to the feature should -be moved into subfolders carrying the name of the release in which they were -shipped (e.g. `2.1`). - -## Sample file layout - -``` -/language - - /working - super-mixins.md - super-mixins-extra.md - mikes-mixins.md - spread-operator.md - mega-constructors/ - proposal.md - alternate.md - illustration.png - - /accepted - 2.0/ - 2.1/ - super-mixins/ - feature-specification.md - future-releases/ - spread-operator/ - feature-specification.md - /resources/ - [various supporting documents and resources] -``` - diff --git a/doc/lifecycle_of_a_language_feature.md b/doc/lifecycle_of_a_language_feature.md new file mode 100644 index 000000000..9e64b806f --- /dev/null +++ b/doc/lifecycle_of_a_language_feature.md @@ -0,0 +1,347 @@ +# Lifecycle of a Dart Language Feature + +This document describes the process from creation to the shipping and release of +a language feature. This document serves as a walkthrough for what's needed to +build a language feature if you're the one driving it. + +1. [User Issues and Feature Requests](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#user-issues-and-feature-requests) +2. [Design, Feedback, and Iteration](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#design-feedback-and-iteration) +3. [Acceptance](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#acceptance) +4. [Team Communication](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#team-communication) (eg. kick-off meetings) +5. [Implementation and Testing](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#implementation-and-testing) +6. [Migrations](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#migrations) +7. [Shipping](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#shipping) + +## User Issues and Feature Requests + +Features arise from perceived user issues or feature requests. These issues are +documentation of the user issue to be solved. + +> [!NOTE] +> These feature requests are filed in the [language repo](https://github.com/dart-lang/language/issues/new?labels=request), +> and are labelled [`request`](https://github.com/dart-lang/language/labels/request). + +We may close issues that we believe we won't address for whatever reason. We may +also keep issues open indefinitely if we believe they are something that we +might want to address in the future. + +### How does the team choose which feature request to accept? + +There are many factors that determine why we might choose to do one feature over +another, such as feasibility, difficulty, or popularity. Often, we will take a +look through the most 👍-reacted issues to see what our users are interested in. + +## Design, Feedback, and Iteration + +Interested parties may propose several (competing) language features to a +single request/problem. + +A "language feature" issue (labelled +[`feature`](https://github.com/dart-lang/language/labels/feature)) +will be created for tracking the solution to the user issue/problem or feature +under consideration. + +### Proposal Checklist + +- [ ] An issue labelled `feature` for discussion of a proposed solution. + - [ ] Links to and from the `request` issue they are trying to address. +- [ ] A link to an initial feature specification writeup of the proposed +solution in the `feature` issue. + - [ ] Located in a sub-directory with the name of the feature (`/ +[feature-name]/`), inside the +[`working`](https://github.com/dart-lang/language/tree/master/working) +directory of the language repository. + - [ ] File is named `feature-specification.md`. + - All written plans, specs, and materials must be written using [GitHub +Markdown format](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) format, and must use the `.md` extension. + +Proposals may be iterated on in-place. + +For smaller and non-controversial features, we will sometimes skip this step and +proceed directly to the [Acceptance](#acceptance) phase. + +### External (outside of the language team) Feedback + +We use the Github issue tracker as the primary place for accepting feedback on +proposals, solicited or unsolicited. + +If we solicit feedback, we will open an issue for discussion and feedback. We +highly recommend filing and splitting off different issues for different threads +of discussion. We generally expect to formally solicit at least one round of +feedback on significant changes. + +## Acceptance + +If consensus is reached on a specific proposal and we decide to accept it, a +member of the language team will be chosen to shepherd the implementation. + +The implementation will be tracked via two artifacts: + + - The feature specification document + - The feature project + +### Feature Specification + +The 'feature specification' is **a single canonical writeup of the language +feature** which is to serve as the implementation reference. The feature +specification should follow the [Proposal Checklist](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#proposal-checklist). + +Once we've chosen a specification, we'll update it throughout the implementation +process. For example, we could add new information to the specification if we +encounter edge-cases we didn't think of initially or remove parts of it if a +certain behavior isn't feasible to implement. + +### Feature Project + +We'll [create a project](https://github.com/orgs/dart-lang/projects) in +dart-lang with the title `[Language] `. This project will link to +and from all the Github issues that we need to track to complete and ship the +feature. + +> [!TIP] +> Generate all the issues for the project automatically with +> https://github.com/itsjustkevin/aviary. +> +> This script generates all the issues that need to be tracked and added to the +> project. If there are any issues or implementation areas that are unnecessary, +> you can close them out immediately, but each issue is worth thinking through. + +#### Meta Implementation Issue + +The meta implementation issue (labelled `implementation`) will be filed in the +language repository for tracking the implementation process. + +This issue must contain links to: + + - [ ] The related `request` and `feature` issues (if they exist) + - [ ] A link to the feature specification + - [ ] All implementation issues + +## Team Communication + +One of the most important parts of the language feature process is communicating +with all the implementation teams and any other stakeholders. + +### Channels for Communication + +We'll send out an announcement email to the entire team, letting them know that +work for the feature is beginning. + +We may create a mailing list or a Google chat group to organize communication +between the different teams working on the language feature. + +### Kick-off Meetings + +We need to get sign-off from all of the relevant implementation teams indicating +that they understand the proposal, believe that it can reasonably be +implemented, and feel that they have sufficient details to proceed. We do this +in the form of kick-off meetings. + +Since feature specification documents are usually long and very detailed, we +like to begin this sign-off process with a set of kick-off meetings, typically +one for each affected implementation team. These meetings are on opportunity for +a language team representative to present a broad outline of the new feature, +give some concrete examples, and collect insights from the implementation teams +about what aspects of the implementation might need special attention. + +Get sign-off from the following teams: +- [ ] Analyzer team +- [ ] CFE team +- [ ] Back-end teams: + - [ ] Dart VM Team + - [ ] Dart Web Team + - [ ] Dart2Wasm Team + +> [!NOTE] +> If a feature consists entirely of a new piece of syntactic sugar, it can be +> tempting to assume that it's not necessary to consult with any back-end teams +> since the CFE will lower the new syntax into a kernel form that is already +> supported, but this can be a dangerous assumption. It's easy to forget that +> even in features that appear to consist purely of syntactic sugar, some +> back-end support may be needed in order to properly support single-step +> debugging or hot reload. +> +> Also, some work may need to be done on back-end code generators in order to +> make sure that the new feature is lowered into a form that can be well +> optimized. + +To avoid missing things, we prefer to err on the side of asking teams whether +they're affected, rather than assuming they won't be. + +## Implementation and Testing + +### Feature Flag + +Most new language features should be implemented using a feature flag. The +feature flag serves several purposes: + +- It allows the feature to be implemented over a series of CLs without + destabilizing the SDK. If it comes time to ship a new release of the SDK + before the feature is ready, the feature flag can remain off, so users won't + be exposed to a partially-implemented or buggy feature before it's ready. +- It allows users to opt in to trying out features that have not yet been + released, by turning on the feature flag locally. +- Once the feature is enabled, the feature flag logic ensures that it will only + affect users who have set their language version to a version that includes + the new feature. This is especially important for package developers who may + want to support a range of versions of the Dart SDK. + +> [!NOTE] +> Implementing a language feature using a feature flag is frequently +> more work that implementing it without a feature flag, since the compiler and +> analyzer must faithfully implement both the old and new behaviors. +> Occasionally the language team may decide that the benefits of using a feature +> flag don't justify this extra work. But this is a rare senario. If you are +> working on a feature and believe you don't need to use a feature flag, please +> consult with the language team to be sure. + +#### How to add a new language feature flag + +- [ ] Add an entry to `tools/experimental_features.yaml` describing the feature, in + the top section (above the line that says `Flags below this line are + shipped`). +- [ ] Run `dart pkg/front_end/tool/fasta.dart generate-experimental-flags` to update + `pkg/_fe_analyzer_shared/lib/src/experiments/flags.dart` and + `pkg/front_end/lib/src/api_prototype/experimental_flags_generated.dart`. +- [ ] Run `dart pkg/analyzer/tool/experiments/generate.dart` to update + `pkg/analyzer/lib/src/dart/analysis/experiments.g.dart`. +- [ ] Add a static final declaration to the `Feature` class in + `pkg/analyzer/lib/dart/analysis/features.dart`. +- [ ] Increment the value of `AnalysisDriver.DATA_VERSION` in + `pkg/analyzer/lib/src/dart/analysis/driver.dart`. + +Example CL: https://dart-review.googlesource.com/c/sdk/+/365545 + +> [!TIP] +> Keep a WIP CL which enables your feature flag by default in the latest +> version. Rebase it occasionally to get a good idea of how your feature breaks +> the SDK and other dependencies. This is very helpful for getting insight on +> what migrations and breaking changes you'll be making. + +### Language Testing + +The language team will generally write a preliminary set of language tests for a +feature, in the SDK's `tests/language` subdirectory. These tests are not +intended to be exhaustive, but should illustrate and exercise important and +non-obvious features. Implementation teams are encouraged to write additional +language or unit tests. The language team may also coordinate the writing of +additional tests. + +An important use case for any new language feature is to ensure that the feature +isn't accidentally used by package authors that have not yet opted into a +language version that supports it. So in addition to testing that the new +language feature works when the feature flag is turned on, the tests added to +`tests/language` should verify that when the feature flag is turned off, the +previous behavior of the SDK is preserved. + +One important exception to preserving previous SDK behavior is that it's +permissible (and even encouraged) to improve error messages so that if the user +tries to use a disabled language feature, they receive an error explaining that +they need to enable it, rather than, say, a confusing set of parse errors. + +#### To enable the feature in a language test +```dart +// SharedOptions=--enable-experiment=$FEATURE +``` +Include this comment near the top of the test (before the +first directive), where `$FEATURE` is replaced with the feature name. + +#### To disable the feature in a language test +```dart +// @dart=$VERSION +``` +Include this comment near the top of the test (before the first directive), +where `$VERSION` is the current stable release of Dart (and therefore is the +largest version that is guaranteed _not_ to contain the feature). + +### Google3 testing + +New features should be tested in Google's internal code base before they are +switched on. + +Details of how to do this will be described in a separate (Google internal) +document. + +### Implementation Work + +This is the bulk of creating a new language feature and this stage will take the +most time. + +Here are some tips for the implementation stage: + +- All implementation works should be under the experiment flag. +- Use the language tests as a pseudo-checklist for what's left to +implement. +- Some teams may have their own checklist for what needs to be considered in a +new language feature implementation. For example, +[this analyzer doc](https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/doc/process/new_language_feature.md) +and [this analysis server doc](https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server/doc/process/new_language_feature.md). +- As we work through an implementation, we may encounter problems or holes in +the spec. If so, create a new issue, add the feature label to it, and cc +@dart-lang/language-team to discuss if we should make any changes in the +specification. + +> [!NOTE] +> Remember that making a language feature is a two way street between the spec +> writers and the implementers. The implementation may change because the spec +> changed, or the spec might change after finding out the implementation is too +> complex. + +## Migrations + +Once the implementation is finished, you should start a CL that enables the +feature by default, if you haven't already. Use this CL to check what code your +feature will break and determine if you need any other lints or quick-fixes to +help these migrations. + +See [Google3 testing](#google3-testing) for more information on fixing breakages +within Google3. + +## Shipping + +This is a general checklist for shipping a feature: +- [ ] Make sure all pre-migrations are complete. +- [ ] Submit a CL that enables the feature by default in the upcoming version. +- [ ] Follow up on documentation changes which should come out when the stable +version with your feature comes out. +- [ ] Communicate with the team that there's a new feature and invite everyone +to test it out. + +Congratulations! You've now shipped the feature. + +Keep an eye out for breakages and any new QOL requests that surface from the +usage of the feature. Sometimes people use features in ways we don't expect and +we can learn a lot from seeing how the feature is used in the real world. + +### After shipping + +After a feature has been shipped, the documents pertaining to the feature should +be moved into subfolders carrying the name of the release in which they were +shipped (e.g. `2.1`). + +#### Sample file layout + +``` +/language + + /working + super-mixins.md + super-mixins-extra.md + mikes-mixins.md + spread-operator.md + mega-constructors/ + proposal.md + alternate.md + illustration.png + + /accepted + 2.0/ + 2.1/ + super-mixins/ + feature-specification.md + future-releases/ + spread-operator/ + feature-specification.md + /resources/ + [various supporting documents and resources] +``` From 99b6d73060cb0e71b373052aecbd7c23e358b47c Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 28 Oct 2024 23:29:35 +0000 Subject: [PATCH 2/4] Rename. --- ...cle_of_a_language_feature.md => life_of_a_language_feature.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{lifecycle_of_a_language_feature.md => life_of_a_language_feature.md} (100%) diff --git a/doc/lifecycle_of_a_language_feature.md b/doc/life_of_a_language_feature.md similarity index 100% rename from doc/lifecycle_of_a_language_feature.md rename to doc/life_of_a_language_feature.md From 236ef3c1cb8a5f1fe9674c7defb673258cde3784 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 28 Oct 2024 23:36:17 +0000 Subject: [PATCH 3/4] Remove typo. --- doc/life_of_a_language_feature.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/life_of_a_language_feature.md b/doc/life_of_a_language_feature.md index 9e64b806f..765fdb26f 100644 --- a/doc/life_of_a_language_feature.md +++ b/doc/life_of_a_language_feature.md @@ -2,7 +2,7 @@ This document describes the process from creation to the shipping and release of a language feature. This document serves as a walkthrough for what's needed to -build a language feature if you're the one driving it. +build a language feature. 1. [User Issues and Feature Requests](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#user-issues-and-feature-requests) 2. [Design, Feedback, and Iteration](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#design-feedback-and-iteration) @@ -191,7 +191,7 @@ feature flag serves several purposes: > more work that implementing it without a feature flag, since the compiler and > analyzer must faithfully implement both the old and new behaviors. > Occasionally the language team may decide that the benefits of using a feature -> flag don't justify this extra work. But this is a rare senario. If you are +> flag don't justify this extra work. But this is a rare scenario. If you are > working on a feature and believe you don't need to use a feature flag, please > consult with the language team to be sure. From 22c70a29ac87b20b8a87e258d1ac6d8bcf4547a4 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 4 Nov 2024 19:19:35 +0000 Subject: [PATCH 4/4] Update naming of headings and fix typos. --- doc/life_of_a_language_feature.md | 46 +++++++++++++++---------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/life_of_a_language_feature.md b/doc/life_of_a_language_feature.md index 765fdb26f..59c6f5d90 100644 --- a/doc/life_of_a_language_feature.md +++ b/doc/life_of_a_language_feature.md @@ -1,18 +1,18 @@ -# Lifecycle of a Dart Language Feature +# Lifecycle of a language feature This document describes the process from creation to the shipping and release of a language feature. This document serves as a walkthrough for what's needed to build a language feature. -1. [User Issues and Feature Requests](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#user-issues-and-feature-requests) -2. [Design, Feedback, and Iteration](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#design-feedback-and-iteration) +1. [User issues and feature requests](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#user-issues-and-feature-requests) +2. [Design, feedback, and iteration](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#design-feedback-and-iteration) 3. [Acceptance](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#acceptance) -4. [Team Communication](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#team-communication) (eg. kick-off meetings) -5. [Implementation and Testing](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#implementation-and-testing) +4. [Team communication](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#team-communication) (eg. kick-off meetings) +5. [Implementation and testing](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#implementation-and-testing) 6. [Migrations](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#migrations) 7. [Shipping](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#shipping) -## User Issues and Feature Requests +## User issues and feature requests Features arise from perceived user issues or feature requests. These issues are documentation of the user issue to be solved. @@ -31,7 +31,7 @@ There are many factors that determine why we might choose to do one feature over another, such as feasibility, difficulty, or popularity. Often, we will take a look through the most 👍-reacted issues to see what our users are interested in. -## Design, Feedback, and Iteration +## Design, feedback, and iteration Interested parties may propose several (competing) language features to a single request/problem. @@ -41,7 +41,7 @@ A "language feature" issue (labelled will be created for tracking the solution to the user issue/problem or feature under consideration. -### Proposal Checklist +### Proposal checklist - [ ] An issue labelled `feature` for discussion of a proposed solution. - [ ] Links to and from the `request` issue they are trying to address. @@ -60,7 +60,7 @@ Proposals may be iterated on in-place. For smaller and non-controversial features, we will sometimes skip this step and proceed directly to the [Acceptance](#acceptance) phase. -### External (outside of the language team) Feedback +### External (outside of the language team) feedback We use the Github issue tracker as the primary place for accepting feedback on proposals, solicited or unsolicited. @@ -80,10 +80,10 @@ The implementation will be tracked via two artifacts: - The feature specification document - The feature project -### Feature Specification +### Feature specification The 'feature specification' is **a single canonical writeup of the language -feature** which is to serve as the implementation reference. The feature +feature** which serves as the implementation reference. The feature specification should follow the [Proposal Checklist](https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md#proposal-checklist). Once we've chosen a specification, we'll update it throughout the implementation @@ -91,7 +91,7 @@ process. For example, we could add new information to the specification if we encounter edge-cases we didn't think of initially or remove parts of it if a certain behavior isn't feasible to implement. -### Feature Project +### Feature project We'll [create a project](https://github.com/orgs/dart-lang/projects) in dart-lang with the title `[Language] `. This project will link to @@ -106,7 +106,7 @@ feature. > project. If there are any issues or implementation areas that are unnecessary, > you can close them out immediately, but each issue is worth thinking through. -#### Meta Implementation Issue +#### Meta implementation issue The meta implementation issue (labelled `implementation`) will be filed in the language repository for tracking the implementation process. @@ -117,12 +117,12 @@ This issue must contain links to: - [ ] A link to the feature specification - [ ] All implementation issues -## Team Communication +## Team communication One of the most important parts of the language feature process is communicating with all the implementation teams and any other stakeholders. -### Channels for Communication +### Channels for communication We'll send out an announcement email to the entire team, letting them know that work for the feature is beginning. @@ -130,7 +130,7 @@ work for the feature is beginning. We may create a mailing list or a Google chat group to organize communication between the different teams working on the language feature. -### Kick-off Meetings +### Kick-off meetings We need to get sign-off from all of the relevant implementation teams indicating that they understand the proposal, believe that it can reasonably be @@ -168,9 +168,9 @@ Get sign-off from the following teams: To avoid missing things, we prefer to err on the side of asking teams whether they're affected, rather than assuming they won't be. -## Implementation and Testing +## Implementation and testing -### Feature Flag +### Feature flag Most new language features should be implemented using a feature flag. The feature flag serves several purposes: @@ -188,7 +188,7 @@ feature flag serves several purposes: > [!NOTE] > Implementing a language feature using a feature flag is frequently -> more work that implementing it without a feature flag, since the compiler and +> more work than implementing it without a feature flag, since the compiler and > analyzer must faithfully implement both the old and new behaviors. > Occasionally the language team may decide that the benefits of using a feature > flag don't justify this extra work. But this is a rare scenario. If you are @@ -218,7 +218,7 @@ Example CL: https://dart-review.googlesource.com/c/sdk/+/365545 > the SDK and other dependencies. This is very helpful for getting insight on > what migrations and breaking changes you'll be making. -### Language Testing +### Language testing The language team will generally write a preliminary set of language tests for a feature, in the SDK's `tests/language` subdirectory. These tests are not @@ -262,14 +262,14 @@ switched on. Details of how to do this will be described in a separate (Google internal) document. -### Implementation Work +### Implementation work This is the bulk of creating a new language feature and this stage will take the most time. Here are some tips for the implementation stage: -- All implementation works should be under the experiment flag. +- All implementation code should be under the experiment flag. - Use the language tests as a pseudo-checklist for what's left to implement. - Some teams may have their own checklist for what needs to be considered in a @@ -319,7 +319,7 @@ After a feature has been shipped, the documents pertaining to the feature should be moved into subfolders carrying the name of the release in which they were shipped (e.g. `2.1`). -#### Sample file layout +For example, moving `super-mixins` to `2.1` after shipping: ``` /language