diff --git a/README.md b/README.md index d4472270b5..6073ed3c6b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,23 @@ -# THIS REPOSITORY IS NOT YET OPEN FOR PARTICIPATION. -**It's still in the process of being set up** +# Work In Progress + +This repository is primarily a place for the Dart language team to work on +language changes and features, and to solicit and accept feedback and requests. +The repository is still in an experimental stage, so expect changes to the +organization and processes documented here. + +Issues and feature requests relevant to the language and the specification may +be filed [here](https://github.com/dart-lang/language/issues). + +# Organization + +We follow +roughly +[this process](https://github.com/dart-lang/language/doc/life_of_a_language_feature.md) for +planning and rolling out language changes. + +# In flight changes + +Nothing currently active. # Dart Language diff --git a/accepted/README.md b/accepted/README.md new file mode 100644 index 0000000000..26cfa13060 --- /dev/null +++ b/accepted/README.md @@ -0,0 +1,3 @@ +# Accepted proposals for implementation + +This directory holds implementation plan documents for accepted changes. diff --git a/doc/life_of_a_language_feature.md b/doc/life_of_a_language_feature.md new file mode 100644 index 0000000000..52ecf268d3 --- /dev/null +++ b/doc/life_of_a_language_feature.md @@ -0,0 +1,81 @@ +# Dart language change 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](http://github.com/language/issues/). We may close issues +that we believe that we will not adress 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/problem issues are primarily for +documentation of the user problem to be solved. + +## Design, feedback, and iteration + +When (a member of) the language team decides to take up an issue, it may be +desireable to file a specific meta issue for tracking the user problem or +feature under consideration, separate from the issues for the specific +proposals. Alternatively, an already filed feature request/user problem may +serve this purpose. + +Language team members may propose specific feature or solutions to a problem. +Generally, this will involve one or more of: + - Filing an issue for discussion of a proposed solution. + - Preparing an initial writeup of the proposed solution and checking it into +the "working" sub-directory of the language repository. + +Additional materials may be added along side the writeup. + +Proposals may be iterated on in place. + +Alternative proposals should generally have their own issue and/or writeup. + +All proposals should be linked from and link to the the meta issue for the user +problem/feature request they are trying to address. + +### 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. An +implementation plan document will be created in a named sub-directory of the +`accepted` folder with details about the implementation plan and **a link to the +single canonical writeup of the language feature* which is to serve as the +implementation reference. The implementation plan should generally include at +least: + - Affected implementation teams. + - Schedule and release milestones. + - Release flag if required, plan for shipping. + +A meta-issue will be filed in the language repository for tracking the +implementation process. The first task in the meta-issue will be 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. There may be further iteration on +the proposal in this phase. Changes will be done in place on the writeup. + +## Testing + +The language team will generally write a preliminary set of language tests for a +feature. 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. + +## Shipping + +Implementated 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. diff --git a/templates/implementation_meta_issue.txt b/templates/implementation_meta_issue.txt new file mode 100644 index 0000000000..7bf4675abe --- /dev/null +++ b/templates/implementation_meta_issue.txt @@ -0,0 +1,27 @@ +Title: Implementation tracking issue for + +Assignee: +Labels: +Projects: + +Body: + +This issue is for tracking implementation of . + +The implementation plan for this issue is . + +## TODO: + +- [ ] Implementation team sign off (this issue): +- [ ] Issue for implementation in dart2js: +- [ ] Issue for implementation in DDC: +- [ ] Issue for implementation in CFE: +- [ ] Issue for implementation in Analyzer: +- [ ] Issue for implementation in Intellij: +- [ ] Issue for implementation in Dartfmt: +- [ ] Issue for implementation in Dartdoc: +- [ ] Issue for implementation in Angular compiler: +- [ ] Issue for language tests: +- [ ] Issue for documentation: +- [ ] Issue for specification: +- [ ] Issue for code cleanup: diff --git a/issues/0006. Super-invocations in mixins/0007. Mixin declarations/lrhn-strawman.md b/working/0006. Super-invocations in mixins/0007. Mixin declarations/lrhn-strawman.md similarity index 100% rename from issues/0006. Super-invocations in mixins/0007. Mixin declarations/lrhn-strawman.md rename to working/0006. Super-invocations in mixins/0007. Mixin declarations/lrhn-strawman.md diff --git a/working/README.md b/working/README.md new file mode 100644 index 0000000000..d843d8d389 --- /dev/null +++ b/working/README.md @@ -0,0 +1,5 @@ +# Working directory + +This directory holds work in progress artifacts in any stage from rough +brainstorming documents to "out-for-implementation" proposals. Don't take +anything in here too seriously.