Update the lifecycle of a language feature documentation. #4143
Conversation
|
|
||
| - The related `request` and `feature` issues (if they exist) | ||
| We'll [create a project](https://github.com/orgs/dart-lang/projects) in |
There was a problem hiding this comment.
I much prefer using issues over projects; projects get unwieldy fast, and are harder for most to consume. I think especially given GitHub is working on rolling out support for sub-issues, we should not recommend using projects, and just stick with meta-issues for now. That also seems like it's what is being discussed below?
https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues
There was a problem hiding this comment.
I would like to keep this for now. I feel like we've always used projects, even if we do have a meta issue. Plus, as being someone trying to get an understanding of all the open bugs or feedback, it's useful to have them all linked together in one project to look at and they might not always be covered by the umbrella of sub-issues that stem from the one meta issue.
I saw the new sub-issues feature and I haven't had a chance to use it yet. I'll give it a shot for organizing enum shorthands and I'll update the doc once we do.
| 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) |
There was a problem hiding this comment.
Once I learned that GitHub will auto-generate a live TOC for you:
I stopped hand-maintaining them. I won't tell you how long it took me to discover this feature.
There was a problem hiding this comment.
Ah yeaah, I knew about that feature, but purposefully made a TOC. If we prefer, we can remove it, I just really like showing all the sections up front at the start of the document.
|
Gonna merge this PR now. I can make more follow-up changes if we feel strongly about anything else. Thanks everyone! |
I've been working on adding to this doc on and off for the last few weeks and I wanted it to reflect my experience and learnings from making language features.
I highly recommend "View file" so you can see the way tips and notes are displayed.
cc. @dart-lang/language-team feel free to review if you'd like. I'll tag a few of you, but I welcome any review. This doc should represent how our team works on and communicates languages features.
Changes
Reformatted some of the sections, added some more info, removed some info. Added some tips and resources that I've found helpful.
The changes are written realistically, and this isn't an aspirational doc. I've done all the steps that I've written down, with the exception of sending an email to the team to let them know that work is starting on a certain feature (although, I would like to do that for the next language feature I work on).
Added a table of contents with 7 different sections, in somewhat the order that we do them in. Some things run concurrently or we might go back and forth in some stages, but this is the general outline.
I tried to be descriptive about each section and what resources/checklists to use. Might still be missing some parts (especially in the migration and implementation sections), but we can iterate.
I've added @itsjustkevin 's script for generating new issues for a feature. It simplifies the process and needing to remember what issues or teams to talk to.