[wiki migration] Remaining pages under docs/contributing/ (#148790)

This commit is contained in:
Kate Lovett 2024-05-23 15:19:04 -05:00 committed by GitHub
parent de0fbdefe3
commit 65abc95542
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
21 changed files with 153 additions and 172 deletions

1
.github/labeler.yml vendored
View file

@ -163,6 +163,7 @@ team:
- changed-files:
- any-glob-to-any-file:
- docs/about/**/*
- docs/contributing/**/*
- docs/postmortems/**/*
team-android:

View file

@ -1314,6 +1314,7 @@ Future<void> verifyRepositoryLinks(String workingDirectory) async {
'flutter/flutter_gallery_assets', // TODO(guidezpl): remove when subtask in https://github.com/flutter/flutter/issues/121564 is complete
'flutter/flutter-intellij', // TODO(guidezpl): remove when https://github.com/flutter/flutter-intellij/issues/7342 is closed
'flutter/platform_tests', // TODO(guidezpl): remove when subtask in https://github.com/flutter/flutter/issues/121564 is complete
'flutter/web_installers',
'glfw/glfw',
'GoogleCloudPlatform/artifact-registry-maven-tools',
'material-components/material-components-android', // TODO(guidezpl): remove when https://github.com/material-components/material-components-android/issues/4144 is closed

View file

@ -49,11 +49,11 @@ Each channel describes its topic in the channel description. Please read the cha
## Policies
Our [code of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md) applies to the Discord server, as it does to any communications involving Flutter.
Our [code of conduct](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md) applies to the Discord server, as it does to any communications involving Flutter.
The #hackers-* channels are visible to anyone, but please only post in those channels if you are actively contributing. If you want help with your app, ask in #help instead. If you want to learn how to contribute, have a look at our [contributing guide](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md).
The #hackers-* channels are visible to anyone, but please only post in those channels if you are actively contributing. If you want help with your app, ask in #help instead. If you want to learn how to contribute, have a look at our [contributing guide](https://github.com/flutter/flutter/blob/main/CONTRIBUTING.md).
See the [[contributor access]] wiki page for details on becoming a member of the "team" role.
See the [contributor access](Contributor-access.md) wiki page for details on becoming a member of the "team" role.
Please don't direct-message people unless they are comfortable with it (ask publicly first).
You can disable direct messages on this server by changing your Privacy settings for the server, or on a global basis by changing your Privacy & Safety user settings.
@ -71,4 +71,4 @@ You can [change your status](https://support.discord.com/hc/en-us/articles/36003
# Design documents
This page used to discuss how to create design docs, but that content is now on its own page: [[Design documents]].
This page used to discuss how to create design docs, but that content is now on its own page: [Design documents](Design-Documents.md).

View file

@ -2,29 +2,29 @@ For people who make the occasional contribution to Flutter (filing an issue, sub
We grant commit access (which includes full rights to the issue database, such as being able to edit labels, and grants access to our internal chat channels) to people who have gained our trust and demonstrated a commitment to Flutter.
Specifically, if you meet one of the following criteria and you have a sponsor (someone who already has contributor access and agrees that you should be granted access), then please ask your sponsor to propose, on the #server-support [[chat]] channel, that you be made a member of the team, and then reply to that message explaining which criteria below you are claiming to meet. The possible criteria are:
Specifically, if you meet one of the following criteria and you have a sponsor (someone who already has contributor access and agrees that you should be granted access), then please ask your sponsor to propose, on the #server-support [Chat](Chat.md) channel, that you be made a member of the team, and then reply to that message explaining which criteria below you are claiming to meet. The possible criteria are:
* You have a long history of participating productively, e.g. in our [[chat]] channels, helping with [[Triage]], helping other contributors track down problems, finding meaningful issues in submitted PRs, helping people in our #help channel, etc, all while demonstrating exemplary behavior that closely aligns with our [code of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md).
* You have a long history of participating productively, e.g. in our [Chat](Chat.md) channels, helping with [Triage](https://github.com/flutter/flutter/wiki/Triage), helping other contributors track down problems, finding meaningful issues in submitted PRs, helping people in our #help channel, etc, all while demonstrating exemplary behavior that closely aligns with our [code of conduct](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md).
* You have recently submitted several PRs that have landed successfully (received an LGTM, PR was merged, no regressions reported, PR was not reverted), without needing extensive tutoring in the process.
* You are employed by a company with a history of contributing to Flutter, for the purpose of yourself regularly contributing to Flutter.
* You represent a development team that creates applications, plugins, or packages using Flutter and have a close relationship with our developer relations team, including having a customer label, and have a great need to regularly update labels on issues (see [Issue hygiene, Customers](https://github.com/flutter/flutter/wiki/Issue-hygiene#customers)). (This is rare.)
* You represent a development team that creates applications, plugins, or packages using Flutter and have a close relationship with our developer relations team, including having a customer label, and have a great need to regularly update labels on issues (see [Issue hygiene, Customers](./issue_hygiene/README.md#customers)). (This is rare.)
Being granted access means that you will be added to the "flutter-hackers" group on GitHub and the "team" role on Discord. This privilege is granted with some expectation of responsibility: contributors are people who care about Flutter and want to help Flutter along our [[roadmap]]. A contributor is not just someone who can make changes or comment on issues, but someone who has demonstrated their ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, follow through to fix bugs (in code or tests), and provide meaningful insights on issues.
Being granted access means that you will be added to the "flutter-hackers" group on GitHub and the "team" role on Discord. This privilege is granted with some expectation of responsibility: contributors are people who care about Flutter and want to help Flutter along our [roadmap](https://github.com/flutter/flutter/wiki/Roadmap). A contributor is not just someone who can make changes or comment on issues, but someone who has demonstrated their ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, follow through to fix bugs (in code or tests), and provide meaningful insights on issues.
We grant access optimistically based on a reasonably small volume of evidence of good faith. Correspondingly, we will remove access quickly if we find our trust has been violated. Contributors with commit access must still follow all our processes and policies, and must follow our [code of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md) rigorously. (Please read it, it's stricter than most.)
We grant access optimistically based on a reasonably small volume of evidence of good faith. Correspondingly, we will remove access quickly if we find our trust has been violated. Contributors with commit access must still follow all our processes and policies, and must follow our [code of conduct](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md) rigorously. (Please read it, it's stricter than most.)
### Responsibilities
#### Code of conduct
If you have commit access or "team" access on the Discord server, you are responsible for enforcing our [code of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md).
If you have commit access or "team" access on the Discord server, you are responsible for enforcing our [code of conduct](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md).
Our code of conduct is much, much stricter than most. We do not wait until someone has been actively rude or insulting. Being disrespectful in any way is grounds for action. For example, passive-aggressive whining and general unconstructive negativity are all violations of the code of conduct. If someone is in a bad mood, we would rather they avoided contributing to Flutter on that day.
When you see something that might be described as unwelcoming or is in some other way a violation of our code of conduct, promptly contact the offender and ask them to read the code of conduct and consider how they might more effectively espouse its philosophy. Most people react very positively to this.
If they react negatively, or if they continue to make the environment unpleasant, they should be removed from the environment. On Discord, this would be kicking them from the channel. Repeat offenders should be banned. On GitHub, they can be blocked from our organisation (you may need to ask @Hixie or another admin of our GitHub org to do this). Please let the #server-support [[chat]] channel know when you do anything like this, so that we can keep an eye on how common it is.
If they react negatively, or if they continue to make the environment unpleasant, they should be removed from the environment. On Discord, this would be kicking them from the channel. Repeat offenders should be banned. On GitHub, they can be blocked from our organisation (you may need to ask @Hixie or another admin of our GitHub org to do this). Please let the #server-support [Chat](Chat.md) channel know when you do anything like this, so that we can keep an eye on how common it is.
#### Maintaining documentation
@ -36,9 +36,9 @@ For the wiki specifically, since there's no code review, it's good to mention on
Being in the GitHub "flutter-hackers" group gives you the following:
* The ability to merge your own PRs once they are reviewed (see [[Tree Hygiene]]).
* The ability to merge your own PRs once they are reviewed (see [Tree Hygiene](Tree-hygiene.md)).
* The ability to add labels, milestones, etc, on issues on GitHub (see [[Issue Hygiene]]).
* The ability to add labels, milestones, etc, on issues on GitHub (see [Issue Hygiene](./issue_hygiene/README.md)).
* PRs will run their tests slightly faster.
@ -69,7 +69,7 @@ The actual process (as followed by Flutter repo admins) is as follows:
We occasionally check for account with commit access that have not been used for a while. It takes very little to count as "active" (e.g. commenting on an issue, even adding an emoji reaction to an issue). If your account has been inactive for over a year we will try to reach out (e.g. by e-mail or on Discord) before removing access.
If your account access was removed but you wish to return to contributing to Flutter, you are most welcome to do so; just reach out on the Discord (see [[Chat]]) and ask someone to renominate you according to the process described above.
If your account access was removed but you wish to return to contributing to Flutter, you are most welcome to do so; just reach out on the Discord (see [Chat](Chat.md)) and ask someone to renominate you according to the process described above.
# Access rights to Flutter dashboard
@ -99,13 +99,13 @@ If you need access to triage images in [Flutter Gold](https://flutter-gold.skia.
Users in the `@google.com` domain are already authorized to use Flutter Gold, but `@gmail.com` addresses can also be added to the allow list.
## Process
The list of authorized users is maintained in the [skia build-bot repository](https://skia.googlesource.com/buildbot), in [this file](https://skia.googlesource.com/buildbot/+/refs/heads/master/golden/k8s-instances/flutter/flutter-skiacorrectness.json5). Googlers can submit a change to add to the authorized users.
The list of authorized users is maintained in the [skia build-bot repository](https://skia.googlesource.com/buildbot), in [this file](https://skia.googlesource.com/buildbot/+/refs/heads/main/golden/k8s-instances/flutter/flutter-skiacorrectness.json5). Googlers can submit a change to add to the authorized users.
This repository is also [mirrored on GitHub.](https://github.com/google/skia-buildbot)
# fcontrib.org accounts
If you are a team member who wants to share design docs (see [[Chat]]) but you don't want to use your own personal account, you can ask a Flutter admin for an fcontrib.org account. Ping @Hixie or another admin in the #server-support channel on Discord.
If you are a team member who wants to share design docs (see [Chat](Chat.md)) but you don't want to use your own personal account, you can ask a Flutter admin for an fcontrib.org account. Ping @Hixie or another admin in the #server-support channel on Discord.
## Process

View file

@ -350,7 +350,7 @@ The `name` key is required unless the `index` key is provided, and isn't allowed
The `nullability` key is required and indicates the type of change made to the parameter. Currently `non_null` is the only type change that is supported.
The `argumentValue` key is optional and if provided will be used as the default value of the parameter. The value of the argumentValue key is a [code template](https://github.com/flutter/flutter/wiki/Data-driven-Fixes#code-template) object.
The `argumentValue` key is optional and if provided will be used as the default value of the parameter. The value of the argumentValue key is a [code template](Data-driven-Fixes.md#code-template) object.
For eg, changing the parameter `a` to non null with a default value you would write:

View file

@ -6,7 +6,7 @@ Don't forget to configure your document's Sharing settings so that everyone has
The template discusses how to create a shortlink for your design doc (flutter.dev/go/...). When creating the shortlink, remember to test the URL you are publishing in an incognito window!
Googlers: Design docs must be created by non-corp accounts! See [Contributor Access](https://github.com/flutter/flutter/wiki/Contributor-access#fcontriborg-accounts) for details on getting `fcontrib.org` accounts if you don't want to use your personal GMail account.
Googlers: Design docs must be created by non-corp accounts! See [Contributor Access](Contributor-access.md#fcontriborg-accounts) for details on getting `fcontrib.org` accounts if you don't want to use your personal GMail account.
When you implement a design, document it in the source code in detail. The API documentation is the usual place where we document our designs. It's perfectly reasonable for API docs to be multiple pages long with subheadings (e.g. see the docs for [RenderBox](https://master-api.flutter.dev/flutter/rendering/RenderBox-class.html)!). Do not assume that anyone will ever read your design doc after the discussion has finished. Similarly, do not assume that anyone will look at closed GitHub issues or PR discussions.
@ -26,7 +26,7 @@ If you wish to get feedback on your design doc, you have many options for doing
* If there is an issue already filed on the topic, definitely put a link to the design doc there. People who have found the issue and want to get updates on the topic will have subscribed to the issue, so this is the most effective way to communicate with them.
* File a new issue to track the design doc using [the design doc issue template](https://github.com/flutter/flutter/issues/new?labels=design+doc&template=8_design_doc.yml). Assign it to yourself.
* File a new issue to track the design doc using [the design doc issue template](https://github.com/flutter/flutter/issues/new?template=8_design_doc.yml). Assign it to yourself.
* Post the link on Discord. You can post it to #hidden-chat to just get feedback from team members. You can post it to one or more of the #hackers-* channels if you want feedback from people who are interested in the general area. You can post it to the global #hackers channel if you want feedback from anyone interested in working on Flutter. If you really want feedback, you can post a request to #announcements and publish it to any server that is following ours.

View file

@ -13,7 +13,7 @@
Verify that `adb` is in your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) (that `which adb` prints sensible output).
If you're
[also working on the Flutter engine](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment),
[also working on the Flutter engine](../engine/dev/Setting-up-the-Engine-development-environment.md),
you can use the copy of the Android platform tools in
`.../engine/src/third_party/android_tools/sdk/platform-tools`.
@ -59,6 +59,6 @@ Next steps:
* [Running examples](https://github.com/flutter/flutter/wiki/Running-examples), to see if your setup works.
* [The flutter tool](https://github.com/flutter/flutter/wiki/The-flutter-tool), to learn about how the `flutter` command line tool works.
* [Style guide for Flutter repo](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo), to learn how to write code for Flutter.
* [Tree hygiene](https://github.com/flutter/flutter/wiki/Tree-hygiene), to learn about how to submit patches.
* [Signing commits](https://github.com/flutter/flutter/wiki/Signing-commits), to configure your environment to securely sign your commits.
* [Style guide for Flutter repo](Style-guide-for-Flutter-repo.md), to learn how to write code for Flutter.
* [Tree hygiene](Tree-hygiene.md), to learn about how to submit patches.
* [Signing commits](Signing-commits.md), to configure your environment to securely sign your commits.

View file

@ -1,19 +1,13 @@
:toc: macro
:toc-title:
:toclevels: 99
### Style guide for Flutter repo
⚠️✏️ Changes to the style guide should be announced to the team in the https://discord.com/channels/608014603317936148/608116355836805126[#announcements] channel on https://github.com/flutter/flutter/wiki/Chat[Discord].
Summary
-------
## Summary
Optimize for readability. Write detailed documentation.
Make error messages useful.
Never use timeouts or timers.
Avoid `is`, `print`, `part of`, `extension` and `_`.
Introduction
------------
## Introduction
This document contains some high-level philosophy and policy decisions for the Flutter
project, and a description of specific style issues for some parts of the codebase.
@ -23,15 +17,10 @@ project (the framework itself and all our sample code). Flutter application deve
are welcome to follow this style as well, but this is by no means required. Flutter
will work regardless of what style is used to author applications that use it.
The engine repository uses https://github.com/flutter/engine/blob/master/CONTRIBUTING.md#style[other style guides for non-Dart code]. The language-neutral sections in this document still apply to engine code, however.
The engine repository uses https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style[other style guides for non-Dart code]. The language-neutral sections in this document still apply to engine code, however.
Table of Contents
-----------------
toc::[]
Overview
--------
## Overview
This document describes our approach to designing and programming Flutter,
from high-level architectural principles all the way to indentation rules.
@ -76,8 +65,7 @@ This requires a different and equally important skill when designing APIs: not g
An API is for life, not just for the one PR you are working on.
Philosophy
----------
## Philosophy
### Lazy programming
@ -343,8 +331,7 @@ Template defaults should focus on providing the best developer experience. Templ
See flutter create's templates for an example.
Policies
--------
## Policies
This section defines some policies that we have decided to honor. In the absence of a very specific policy in this section, the general philosophies in the section above are controlling.
@ -392,8 +379,7 @@ All such "third party code" must either be a fork for which we take full respons
In general it is _strongly_ recommended that we avoid any such code unless strictly necessary. In particular, we aim for all code in the flutter/flutter repository to be https://github.com/flutter/flutter/wiki/Why-we-have-a-separate-engine-repo#licensing?[single-licensed], which is why it does not contain any "third party code" at all.
Documentation (dartdocs, javadocs, etc)
---------------------------------------
## Documentation (dartdocs, javadocs, etc)
We use "dartdoc" for our Dart documentation, and similar technologies for the documentation
of our APIs in other languages, such as ObjectiveC and Java. All public members in Flutter
@ -620,13 +606,13 @@ By definition, if they are looking at the documentation, they are not finding it
Sample code helps developers learn your API quickly. Writing sample code also helps you think through how your API is going to be used by app developers.
Sample code should go in a documentation comment that typically begins with `/// {@tool dartpad}`, and ends with `/// {@end-tool}`, with the example source and corresponding tests placed in a file under https://github.com/flutter/flutter/blob/master/examples/api[the API examples directory]. This will then be checked by automated tools, and formatted for display on the API documentation web site https://api.flutter.dev[api.flutter.dev]. For details on how to write sample code, see https://github.com/flutter/flutter/blob/master/examples/api/README.md#authoring[the API example documentation].
Sample code should go in a documentation comment that typically begins with `/// {@tool dartpad}`, and ends with `/// {@end-tool}`, with the example source and corresponding tests placed in a file under https://github.com/flutter/flutter/blob/main/examples/api[the API examples directory]. This will then be checked by automated tools, and formatted for display on the API documentation web site https://api.flutter.dev[api.flutter.dev]. For details on how to write sample code, see https://github.com/flutter/flutter/blob/main/examples/api/README.md#authoring[the API example documentation].
#### Provide full application samples.
Our UX research has shown that developers prefer to see examples that are in the context of an entire app. So, whenever it makes sense, provide an example that can be presented as part of an entire application instead of just a snippet that uses the `{@tool snippet}` or &#96;&#96;&#96;dart ... &#96;&#96;&#96; indicators.
An application sample can be created using the `{@tool dartpad}` ... `{@end-tool}` or `{@tool sample}` ... `{@end-tool}` dartdoc indicators. See https://github.com/flutter/flutter/blob/master/examples/api/README.md#authoring[here] for more details about writing these kinds of examples.
An application sample can be created using the `{@tool dartpad}` ... `{@end-tool}` or `{@tool sample}` ... `{@end-tool}` dartdoc indicators. See https://github.com/flutter/flutter/blob/main/examples/api/README.md#authoring[here] for more details about writing these kinds of examples.
Dartpad examples (those using the dartdoc `{@tool dartpad}` indicator) will be presented on the https://api.flutter.dev[API documentation website] as an in-page executable and editable example. This allows developers to interact with the example right there on the page, and is the preferred form of example. Here is https://api.flutter.dev/flutter/widgets/AnimatedSwitcher-class.html#widgets.AnimatedSwitcher.1[one such example].
@ -741,8 +727,7 @@ When referencing a parameter, use backticks. However, when referencing a paramet
Avoid using terms like "above" or "below" to reference one dartdoc section from another. Dartdoc sections are often shown alone on a Web page, the full context of the class is not present.
Coding patterns and catching bugs early
---------------------------------------
## Coding patterns and catching bugs early
### Use asserts liberally to detect contract violations and verify invariants
@ -809,7 +794,7 @@ global constant.
As a general rule, when you have a lot of constants, wrap them in a
class. For examples of this, see
https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/material/colors.dart[lib/src/material/colors.dart].
https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/material/colors.dart[lib/src/material/colors.dart].
### Avoid using `if` chains or `?:` or `==` with enum values
@ -1045,8 +1030,7 @@ anyway. It should also be avoided in very large functions.
It incurs runtime overhead in maintaining and using an iterator, and space overhead for the compiler
to actually desugar the generator into something that uses an iterator class.
Writing tests
-------------
## Writing tests
### Make each test entirely self-contained
@ -1079,8 +1063,7 @@ As per the API docs for https://main-api.flutter.dev/flutter/flutter_test/Widget
Using `pumpAndSettle`, especially without checking its return value, makes it very easy for bugs to sneak in where we trigger animations across multiple frames instead of immediately. It is almost always the case that a call to `pumpAndSettle` is more strictly correctly written as two `pump` calls, one to trigger the animations and one (with a duration) to jump to the point after the animations.
Naming
------
## Naming
### Begin global constant names with prefix "k"
@ -1190,8 +1173,7 @@ future is higher. Instead find a name that represents the idea being being used
or replaced.
Comments
--------
## Comments
### Avoid checking in comments that ask questions
@ -1272,8 +1254,7 @@ Generally the closure passed to `setState` should include all the code that chan
```
Formatting
----------
## Formatting
These guidelines have no technical effect, but they are still important purely
for consistency and readability reasons.
@ -1798,8 +1779,7 @@ Finally, `+=` is more convenient when changing the increment to a number other t
To make it clearer when something is a double or an integer, even if the number is a round number, include a decimal point in double literals. For example, if a function `foo` takes a double, write `foo(1.0)` rather than `foo(1)` because the latter makes it look like the function takes an integer.
Conventions
-----------
## Conventions
### Expectations around potential crashes in the engine
@ -1847,8 +1827,7 @@ We generally prefer `Listenable` subclasses (e.g. `ValueNotifier` or `ChangeNoti
In the specific case of exposing a value from `dart:ui` via a callback, we expect the bindings in the framework to register a single listener and then provide a mechanism to fan the notification to multiple listeners. Sometimes this is a rather involved process (e.g. the `SchedulerBinding` exists almost entirely for the purpose of doing this for `onBeginFrame`/`onDrawFrame`, and the `GesturesBinding` exists exclusively for the purpose of doing this for pointer events). Sometimes it's simpler (e.g. propagating changes to life cycle events).
Packages
--------
## Packages
### Structure
@ -1856,20 +1835,20 @@ As per normal Dart conventions, a package should have a single import
that reexports all of its API.
> For example,
> https://github.com/flutter/flutter/blob/master/packages/flutter/lib/rendering.dart[rendering.dart]
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/rendering.dart[rendering.dart]
> exports all of lib/src/rendering/*.dart
If a package uses, as part of its exposed API, types that it imports
from a lower layer, it should reexport those types.
> For example,
> https://github.com/flutter/flutter/blob/master/packages/flutter/lib/material.dart[material.dart]
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/material.dart[material.dart]
> reexports everything from
> https://github.com/flutter/flutter/blob/master/packages/flutter/lib/widgets.dart[widgets.dart].
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/widgets.dart[widgets.dart].
> Similarly, the latter
> https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/widgets/basic.dart[reexports]
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/widgets/basic.dart[reexports]
> many types from
> https://github.com/flutter/flutter/blob/master/packages/flutter/lib/rendering.dart[rendering.dart],
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/rendering.dart[rendering.dart],
> such as `BoxConstraints`, that it uses in its API. On the other
> hand, it does not reexport, say, `RenderProxyBox`, since that is not
> part of the widgets API.
@ -1910,7 +1889,7 @@ By convention, `dart:ui` is imported using `import 'dart:ui' show
level will have done it for you), and as `import 'dart:ui' as ui show
...;` for low-level APIs, in both cases listing all the identifiers
being imported. See
https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/painting/basic_types.dart[basic_types.dart]
https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/painting/basic_types.dart[basic_types.dart]
in the `painting` package for details of which identifiers we import
which way. Other packages are usually imported undecorated unless they
have a convention of their own (e.g. `path` is imported `as path`).

View file

@ -2,21 +2,21 @@
- Regressions should be [reverted first](https://github.com/flutter/flutter/wiki/Landing-Changes-With-Autosubmit) and questions asked later. Bringing the tree to green is higher priority.
- A breaking change is one that breaks the tests in the flutter/tests repo, and those need a migration guide.
- Expect that a new patch will be reviewed within two weeks, unless it is fixing a P0 bug in which case it should be reviewed the same day. If it has not been reviewed in that timeframe, reach out on [[Chat]]. Remember that reviewers are human beings with additional professional and personal responsibilities.
- Expect that a new patch will be reviewed within two weeks, unless it is fixing a P0 bug in which case it should be reviewed the same day. If it has not been reviewed in that timeframe, reach out on [Chat](Chat.md). Remember that reviewers are human beings with additional professional and personal responsibilities.
## Introduction
This page covers how to land a PR and other aspects of writing code for
Flutter other than the actual writing of the code. For guidance on
designing APIs, documenting, and formatting your code, see the
[[Style guide for Flutter repo]] document.
[Style guide for Flutter repo](Style-guide-for-Flutter-repo.md) document.
## Overview
The general process for submitting code to a Flutter repository is as follows:
1. Fork the repository on GitHub (see the
[contributing guide](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md)
[contributing guide](https://github.com/flutter/flutter/blob/main/CONTRIBUTING.md)
for advice on doing this and in general setting up your development environment).
2. If there is not already an issue covering the work you are interested in doing,
@ -26,11 +26,11 @@ The general process for submitting code to a Flutter repository is as follows:
before it can land, having an issue means we have somewhere to point to the code when
we close the PR without landing it, so other people can take it over.
3. Discuss your design on the issue. See [[Design Documents]] for advice.
3. Discuss your design on the issue. See [Design Documents](Design-Documents.md) for advice.
You may find it useful to create a Google Doc to
solicit feedback (use the template at [flutter.dev/go/template](https://flutter.dev/go/template)).
You may wish to e-mail the mailing list, or discuss the topic
on our [[Chat]] channels. The more buy-in you get from the rest of the
on our [Chat](Chat.md) channels. The more buy-in you get from the rest of the
team (especially the relevant leads), the easier the rest of the process will be.
You can put the label "proposal" on your issue to indicate that you have a design
up for discussion in the issue.
@ -46,14 +46,14 @@ The general process for submitting code to a Flutter repository is as follows:
having a `main` branch, from `master`) on your GitHub fork of the repository, and implement
your change. Make sure it is tested (see the next section for details).
You must follow the guidelines described in the [[Style guide for Flutter repo]].
You must follow the guidelines described in the [Style guide for Flutter repo](Style-guide-for-Flutter-repo.md).
Files must not have trailing spaces.
For the engine repository, C, C++, and Objective-C code should be formatted with
`clang-format` before submission (use `buildtools/<OS>/clang/bin/clang-format
--style=file -i`).
6. Submit this branch as a PR to the relevant Flutter repository.
_(See also: [[Signing commits]])_
_(See also: [Signing commits](./Signing-commits.md))_
7. Get your code reviewed (see below). You should probably reach out to the relevant
expert(s) for the areas you touched and ask them to review your PR directly.
@ -62,7 +62,7 @@ The general process for submitting code to a Flutter repository is as follows:
8. Make sure your PR passes all the pre-commit tests. Consider running some of the
post-commit tests locally (see the
[devicelab](https://github.com/flutter/flutter/blob/master/dev/devicelab/README.md)
[devicelab](https://github.com/flutter/flutter/blob/main/dev/devicelab/README.md)
directory). If any tests break, especially the `customer_testing` tests, please
see the breaking change policy section below for details on how to proceed.
@ -80,7 +80,7 @@ The general process for submitting code to a Flutter repository is as follows:
goes wrong, revert your patch and study the problem. You should aim to be the one to revert your patch. You will be racing everyone
else on the team who will also be trying to revert your patch. (See below for guidance on reverting PRs.)
_See also: [[What should I work on?]]_
_See also: [What should I work on?](What-should-I-work-on.md)_
## Tests
@ -104,16 +104,16 @@ If a reviewer says a PR should have a test, then it needs a test regardless of t
PRs adding data-driven fixes require tests that fall under the test_fixes directory, but are not yet recognized by the bot as being tested.
Consider using the code coverage tools to check that all your new code is covered by tests (see [[Test coverage for package:flutter]]).
Consider using the code coverage tools to check that all your new code is covered by tests (see [Test coverage for package:flutter](./testing/Test-coverage-for-package-flutter.md)).
Feel free to update the bot's logic to catch more cases that should be automatically exempt (it's in the cocoon repo).
## Using git
Assuming your environment has been configured according to the instructions in
[[Setting up the Engine development environment]],
[[Setting up the Framework development environment]], or
[[Setting up the Packages development environment]],
[Setting up the Engine development environment](../engine/dev/Setting-up-the-Engine-development-environment.md),
[Setting up the Framework development environment](Setting-up-the-Framework-development-environment.md), or
[Setting up the Packages development environment](../ecosystem/contributing/Setting-up-the-Packages-development-environment.md),
follow these steps to start working on a patch:
* `git fetch upstream`
@ -127,7 +127,7 @@ GitHub provides you with a link for submitting the pull request in the message o
Because `git pull` will often miss tags that are used to define the release of the flutter tool, it is recommended to use `git fetch` typically to avoid version mismatches when running `flutter update-packages`.
Use `git fetch upstream; git rebase upstream/main; git push origin your_branch_name` to update your PRs, rather than using merge, because that way our tooling will recognize your PR as being up to date. (Otherwise it'll try testing against the tests at the time you originally branched.) Also, **be wary of force pushing to your PR branch** if you are dealing with golden image tests; see [[gold troubleshooting instructions|Writing-a-golden-file-test-for-package:flutter#troubleshooting]].
Use `git fetch upstream; git rebase upstream/main; git push origin your_branch_name` to update your PRs, rather than using merge, because that way our tooling will recognize your PR as being up to date. (Otherwise it'll try testing against the tests at the time you originally branched.) Also, **be wary of force pushing to your PR branch** if you are dealing with golden image tests; see [gold troubleshooting instructions](./testing/Writing-a-golden-file-test-for-package-flutter.md#troubleshooting).
Please make sure all your patches have detailed commit messages explaining what the problem was and
what the solution is.
@ -141,7 +141,7 @@ You can do this online, and it only takes a minute.
Every PR must be code-reviewed before check-in, including things like
rolling a dependency. Getting a review means that a regular Flutter
contributor (someone with commit access; see [[contributor access]] for details) has "approved" the PR in the
contributor (someone with commit access; see [contributor access](Contributor-access.md) for details) has "approved" the PR in the
GitHub UI. We call this "getting an LGTM" ("looks good to me").
If you are not yourself someone with commit access, then a second person
@ -182,18 +182,18 @@ should be reserved for those with contributor access). The more
reviews the better.
If nobody reviews your PR within two weeks, you can ask for
a review via our [[Chat]] channels. Start by asking in #hackers,
a review via our [Chat](Chat.md) channels. Start by asking in #hackers,
saying what your patch does and providing a link.
### Who
PRs are assigned reviewers weekly. The precise process varies by team but tends to be combined with issue [[triage]].
PRs are assigned reviewers weekly. The precise process varies by team but tends to be combined with issue [triage](https://github.com/flutter/flutter/wiki/Triage).
Code should be reviewed by the owner (tech lead) of the area(s) of the codebase that you are changing,
or someone to whom they have delegated that authority.
If anyone else leaves comments, please also wait for their approval (LGTM) before landing code.
If nobody has reviewed your code after a week, then reach out on our [[Chat]] channels.
If nobody has reviewed your code after a week, then reach out on our [Chat](Chat.md) channels.
The `#hackers-new` channel is a good place to ask for help if you're a new contributor.
_For PRs affecting the `material` and `cupertino` libraries, team members are expected to seek reviewers directly;
@ -210,7 +210,7 @@ Reviewers should carefully read the code and make sure they understand
it. A reviewer should check the code for both high level concerns,
such as whether the approach is reasonable and whether the code's structure makes sense, as well as
lower-level issues like how readable the code is and adherence to the
[Flutter style guide](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo).
[Flutter style guide](Style-guide-for-Flutter-repo.md).
Use [these best practices](https://mtlynch.io/human-code-reviews-1/)
when reviewing code and providing comments.
@ -219,18 +219,18 @@ As a reviewer, you are the last line of defense.
0. Did the author sign the CLA? If not, ask them to do so and don't look at the code.
1. Take a step back. What problem is the PR trying to solve? Is it a real problem?
2. What other solutions could we consider? What could we do to make this even better?
3. Is it the best API? See our [philosophy](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#philosophy) section. Look for state duplication, synchronous slow work, complecting, global state, overly-specific APIs, API cliffs and API oceans, API design in a vacuum (without a customer). If these terms don't make sense, read the style guide again. :-)
4. Is it the best implementation? Again, see our [style guide](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#coding-patterns-and-catching-bugs-early), in particular its section on good coding patterns. Are there hacks? Are we taking on more technical debt? Think of ways in which the code could break.
3. Is it the best API? See our [philosophy](Style-guide-for-Flutter-repo.md#philosophy) section. Look for state duplication, synchronous slow work, complecting, global state, overly-specific APIs, API cliffs and API oceans, API design in a vacuum (without a customer). If these terms don't make sense, read the style guide again. :-)
4. Is it the best implementation? Again, see our [style guide](Style-guide-for-Flutter-repo.md#coding-patterns-and-catching-bugs-early), in particular its section on good coding patterns. Are there hacks? Are we taking on more technical debt? Think of ways in which the code could break.
5. Is it testable? Is it tested? **All code must be tested.** Are there asserts? Encourage liberal use of assertions.
6. Look for mistakes in indenting the code and other trivial formatting problems.
7. Is new code licensed correctly?
8. Is the documentation thorough and useful? Look for useless documentation, empty prose, and breadcrumbs. See the [documentation section](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#documentation-dartdocs-javadocs-etc) of our style guide for what that means.
8. Is the documentation thorough and useful? Look for useless documentation, empty prose, and breadcrumbs. See the [documentation section](hStyle-guide-for-Flutter-repo.md#documentation-dartdocs-javadocs-etc) of our style guide for what that means.
9. Check for good grammar in API docs and comments. Check that identifiers are named according to our conventions.
Once you are satisfied with the contribution, and _only_ once you are satisfied,
use the GitHub "Approval" mechanism (an "LGTM" comment is not sufficient).
If you feel like you are being worn down, hand the review to someone else. Consider
our [conflict resolution](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md#conflict-resolution)
our [conflict resolution](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md#conflict-resolution)
policy if you feel like you are being forced to agree to something you don't like.
Reviewers should not give an LGTM unless the patch has tests that verify
@ -283,7 +283,7 @@ revert (roll back) the check-in (even if it isn't yours). Do not attempt to forw
There is no shame in making mistakes! Reverts happen all the time and are a normal part of engineering.
To revert a PR, just add the `revert` label to it. _For more details, see [[Landing Changes With Autosubmit]]._
To revert a PR, just add the `revert` label to it. _For more details, see [Landing Changes With Autosubmit](https://github.com/flutter/flutter/wiki/Landing-Changes-With-Autosubmit)._
### Avoid "Revert "Revert "Revert "Revert "Fix foo"""" commit messages
@ -383,15 +383,15 @@ Implement the change you wish to see and run the existing tests against your new
The "contributed tests" are:
* Those in the [`customer_testing`](https://github.com/flutter/tests) shard on `flutter/flutter` PRs.
* Additional test suites that we have been allowed to run but that are not public. (Notably, Google allows us to run several tens of thousands of [[proprietary tests|Understanding Google Testing]] on each commit.)
* Additional test suites that we have been allowed to run but that are not public. (Notably, Google allows us to run several tens of thousands of [proprietary tests](https://github.com/flutter/flutter/wiki/Understanding-Google-Testing) on each commit.)
There are no exemptions to this policy, because these tests run in our CI and breaking them will close the tree.
In cases where these tests pass but we can nonetheless imagine reasonable scenarios where developers would be affected negatively, by courtesy, once the change has landed, engineers are encouraged to announce the changes by sending an e-mail to [flutter-announce@](https://groups.google.com/g/flutter-announce), a message to the `#announcements` channel on our [[Chat]], and tagging the relevant issues with the [**c: API break** label](https://github.com/flutter/flutter/labels/c%3A%20API%20break) (such that they will be included in our release notes). However, we do not consider these breaking changes. (One reason to do this would be if we see our own tests being significantly affected, even if no contributed test actually fails.)
In cases where these tests pass but we can nonetheless imagine reasonable scenarios where developers would be affected negatively, by courtesy, once the change has landed, engineers are encouraged to announce the changes by sending an e-mail to [flutter-announce@](https://groups.google.com/g/flutter-announce), a message to the `#announcements` channel on our [Chat](Chat.md), and tagging the relevant issues with the [**c: API break** label](https://github.com/flutter/flutter/labels/c%3A%20API%20break) (such that they will be included in our release notes). However, we do not consider these breaking changes. (One reason to do this would be if we see our own tests being significantly affected, even if no contributed test actually fails.)
### 2. Evaluate the breaking change
If your change counts as a breaking change, seriously consider whether it is truly necessary and beneficial. Consider writing a [[design document|Design Documents]]. Discuss it with your code reviewer. Raise it in [[Chat]].
If your change counts as a breaking change, seriously consider whether it is truly necessary and beneficial. Consider writing a [design document](Design-Documents.md). Discuss it with your code reviewer. Raise it in [Chat](Chat.md).
### 3. Prepare your change.
@ -405,7 +405,7 @@ If possible, avoid four-phase deprecations (adding a new API with a temporary na
Stage your change and the documentation for your change. Typically this will be two or more PRs, plus PRs to fix the tests that were broken (see step 1), as well as writing a migration guide as a PR to the Website repository.
If possible, include flutter fixes to aid users in migration. Whether or not the change is supported by flutter fix should be included in the migration guide. To learn about authoring fixes, see [Data driven Fixes](https://github.com/flutter/flutter/wiki/Data-driven-Fixes).
If possible, include flutter fixes to aid users in migration. Whether or not the change is supported by flutter fix should be included in the migration guide. To learn about authoring fixes, see [Data driven Fixes](Data-driven-Fixes.md).
**Use our [breaking change migration guide template](https://github.com/flutter/website/blob/main/src/release/breaking-changes/template.md)** (follow all the instructions in the comments) to create the migration guide that describes the change. Do not land the migration guide at this time. You will need to update it before you land it in the last step.
@ -423,7 +423,7 @@ Once everything has landed:
* update your migration guide based on your experience migrating everyone,
* update the timeline on the guide, and push it to [the flutter.dev Web site](https://flutter.dev/docs/release/breaking-changes) (don't forget to update the [index](https://github.com/flutter/website/blob/main/src/release/breaking-changes/index.md) of that directory as well),
* e-mail a copy to [flutter-announce@](https://groups.google.com/g/flutter-announce),
* notify the `#announcements` channel on our [[Chat]], and
* notify the `#announcements` channel on our [Chat](Chat.md), and
* add the [**c: API break** label](https://github.com/flutter/flutter/labels/c%3A%20API%20break) to the relevant issues, so they get listed in the upcoming Release notes.
### Deprecations
@ -454,7 +454,7 @@ Using this standard form ensures that we can write a script to detect all deprec
To determine the latest beta version, see <https://flutter.dev/docs/development/tools/sdk/releases>.
When adding a deprecation notice to the framework, a flutter fix should be included with your change. This helps users migrate to the new API as easily as possible. To learn more about authoring fixes, see [Data driven Fixes](https://github.com/flutter/flutter/wiki/Data-driven-Fixes). If a fix cannot be written for the new API, please file an issue in https://github.com/dart-lang/sdk and link to it in your change.
When adding a deprecation notice to the framework, a flutter fix should be included with your change. This helps users migrate to the new API as easily as possible. To learn more about authoring fixes, see [Data driven Fixes](Data-driven-Fixes.md). If a fix cannot be written for the new API, please file an issue in https://github.com/dart-lang/sdk and link to it in your change.
When deprecating features, be aware that *you* will not by default be informed when the Flutter code itself uses the deprecated feature (there is a `deprecated_member_use_from_same_package: ignore` line in the root `analysis_options.yaml` file). To find places where the old feature is used, rename its declaration and see where the compiler complains. (You can't just comment out the "ignore" in the `analysis_options.yaml` file because it's hiding hundreds of other warnings...)

View file

@ -8,8 +8,8 @@ This page attempts to be a one-stop shop for figuring out what the most importan
1. [Flaky tests](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22team%3A+flakes%22+sort%3Aupdated-asc).
1. Performance regressions. Check the [dashboard](https://flutter-dashboard.appspot.com/benchmarks.html) for new unreported regressions and see GitHub for the list of [reported performance regressions](https://github.com/flutter/flutter/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3A%22c%3A+performance%22+label%3A%22c%3A+regression%22+).
1. [Other regressions](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22c%3A+regression%22).
1. Reducing technical debt. (For example, increasing [our test coverage](https://github.com/flutter/flutter/wiki/Test-coverage-for-package%3Aflutter) by [writing new tests](https://github.com/flutter/flutter/wiki/Running-and-writing-tests), or fixing TODOs.)
1. [P2 issues](https://github.com/flutter/flutter/labels/P1), which correspond to the remaining areas of our [[roadmap]], such as:
1. Reducing technical debt. (For example, increasing [our test coverage](./testing/Test-coverage-for-package-flutter.md) by [writing new tests](./testing/Running-and-writing-tests.md), or fixing TODOs.)
1. [P2 issues](https://github.com/flutter/flutter/labels/P1), which correspond to the remaining areas of our [roadmap](https://github.com/flutter/flutter/wiki/Roadmap), such as:
* Bugs marked as [annoyances](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22a%3A+annoyance%22+sort%3Areactions-%2B1-desc).
* Bugs labeled as issues of [quality](https://github.com/flutter/flutter/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22a%3A+quality%22+sort%3Areactions-%2B1-desc+).
* Bugs with the [crash](https://github.com/flutter/flutter/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22c%3A+crash%22+sort%3Areactions-%2B1-desc+) label.
@ -18,10 +18,10 @@ This page attempts to be a one-stop shop for figuring out what the most importan
Bugs in other bug systems should be tracked with bugs in GitHub. OKRs should be reflected in the items listed above. For example, OKRs should reflect what the roadmap covers, expected customer blockers, and so forth. Work that is unique to a particular quarter would be represented by a filed bug with a milestone and assignee.
During [[triage]], bugs should be prioritized according to the [P0-P3 labels](https://github.com/flutter/flutter/wiki/Issue-hygiene#priorities) so as to fit the order described above.
During [triage](https://github.com/flutter/flutter/wiki/Triage), bugs should be prioritized according to the [P0-P3 labels](./issue_hygiene/README.md#priorities) so as to fit the order described above.
Sometimes, items in the list above escalate. For example, a bug might get filed as a P2 issue, then be recognized as a critical regression and upgraded to P0.
See also:
* [[Issue Hygiene]], in particular the section on prioritization.
* [Issue Hygiene](./issue_hygiene/README.md), in particular the section on prioritization.

View file

@ -16,7 +16,7 @@ There are three main areas that people are referring to here:
* **Modular application delivery**: the ability to package a single app into multiple separate archives when compiling it, and download them independently as needed. This is supported on Android via [deferred components](https://docs.flutter.dev/perf/deferred-components). We suspect it is not possible to achieve this on iOS with Apple's current guidelines and tools. We have not yet attempted to provide this on desktop or web, primarily because we have more important issues to resolve on those platforms first.
* **Dynamic extension loading**: the ability to download some Dart code that wasn't written when the app was first published, which adds a new feature to the app. This could be done on the fly. It may require the core app to be larger since we can't know ahead of time what is needed by each future extension. There are various solutions in this space, such as combining [the rfw package](https://pub.dev/packages/rfw) and an FFI-based or Wasm-based solution (e.g. [package:wasm](https://pub.dev/packages/wasm)). There is [an example](https://github.com/flutter/packages/tree/master/packages/rfw/example/wasm) that provides a proof-of-concept for this combination of packages: a Flutter desktop application that knows nothing about being a calculator downloads an interface description specifying all the buttons and their layout to show on the screen, and downloads a C program compiled to Wasm to perform the calculations. The Flutter program is merely a bridge between these two downloaded files. We are looking for feedback from people using this feature; please add your experiences to [issue 90218](https://github.com/flutter/flutter/issues/90218).
* **Dynamic extension loading**: the ability to download some Dart code that wasn't written when the app was first published, which adds a new feature to the app. This could be done on the fly. It may require the core app to be larger since we can't know ahead of time what is needed by each future extension. There are various solutions in this space, such as combining [the rfw package](https://pub.dev/packages/rfw) and an FFI-based or Wasm-based solution (e.g. [package:wasm](https://pub.dev/packages/wasm)). There is [an example](https://github.com/flutter/packages/tree/main/packages/rfw/example/wasm) that provides a proof-of-concept for this combination of packages: a Flutter desktop application that knows nothing about being a calculator downloads an interface description specifying all the buttons and their layout to show on the screen, and downloads a C program compiled to Wasm to perform the calculations. The Flutter program is merely a bridge between these two downloaded files. We are looking for feedback from people using this feature; please add your experiences to [issue 90218](https://github.com/flutter/flutter/issues/90218).
* **Dynamic patching**: the ability to update the Dart code of an app in the field by downloading a patch (of sorts) and providing it to the Dart VM. This would require a reload of the app to take effect. Dynamic patching was previously on our roadmap for 2019. After investigating this in greater detail, we decided not to proceed with that work. There were several factors that led us to this decision:
@ -32,13 +32,13 @@ There are three main areas that people are referring to here:
Currently, we see this as a lower priority than our other release-related work (such as working towards [SLSA compliance](https://slsa.dev)). There are a number of other mechanisms for obtaining Flutter today, so this does not immediately unblock anyone, it is "merely" a convenience. That said, we recognize that homebrew is a pretty idiomatic way of getting software for developers on macOS, and so the request is quite valid.
If anyone would be interested in implementing an official homebrew installation path, the best thing to do would be to reach out on the #hackers-releases channel of our Discord (see [[Chat]]). Implementing it would require integrating into our release pipeline, so familiarity with that would be extremely helpful. It would also require carefully negotiating how Flutter's primary distribution mechanism (shipping the `git` repo directly) should interact with Homebrew's mechanisms, so familiarity with both of those would also be needed.
If anyone would be interested in implementing an official homebrew installation path, the best thing to do would be to reach out on the #hackers-releases channel of our Discord (see [Chat](../Chat.md)). Implementing it would require integrating into our release pipeline, so familiarity with that would be extremely helpful. It would also require carefully negotiating how Flutter's primary distribution mechanism (shipping the `git` repo directly) should interact with Homebrew's mechanisms, so familiarity with both of those would also be needed.
## [Design a new vector file format](https://github.com/flutter/flutter/issues/1831) (#1831)
A [design document](https://flutter.dev/go/vector-graphics) containing both a detailed study of the problem and a strawman proposal have been published (comments welcome). The primary goal of the strawman proposal is to see if it is possible to create a format that is implemented entirely on the GPU (the thought being that creating yet another CPU-bound format doesn't really bring the industry forward). The next step is to experiment with implementing the proposal. Unfortunately all our shader experts are currently busy on higher-priority problems (like improving rendering performance and reducing jank), so this work has stalled.
As usual, contributions are welcome. Reach out to Hixie directly (either by e-mail, ian@hixie.ch, or on our [[Chat]] channels) if you are interested in helping out.
As usual, contributions are welcome. Reach out to Hixie directly (either by e-mail, ian@hixie.ch, or on our [Chat](../Chat.md) channels) if you are interested in helping out.
## [Enable "hot reload" (not just "hot restart") for Flutter Web](https://github.com/flutter/flutter/issues/53041) (#53041)
@ -49,7 +49,7 @@ to see progress soon. It is a technically extremely difficult and subtle problem
This feature is one that is recognized as important. There are some prerequisites, like improving Flutter's deep linking and accessibility features, which we have to deal with first. There are also other issues, like those around performance, plugins, and embedding, that are currently higher on the list for people who are currently contributing to Flutter's web support.
Fixing this issue is non-trivial, as Flutter's architecture is one that is fundamentally different than what the web usually expects. If you are interested in contributing, the best place to begin would be to discuss potential approaches on our #hackers-web [[Chat]] channel, followed by writing up a design doc (the process for which is also on the [[Chat]] page).
Fixing this issue is non-trivial, as Flutter's architecture is one that is fundamentally different than what the web usually expects. If you are interested in contributing, the best place to begin would be to discuss potential approaches on our #hackers-web [Chat](../Chat.md) channel, followed by writing up a design doc (the process for which is also on the [Chat](../Chat.md) page).
## [Bring Material 3 to Flutter](https://github.com/flutter/flutter/issues/91605) (#91605)

View file

@ -33,7 +33,7 @@ Adding comments explaining how a bug is dire and how you will stop using Flutter
if it is not fixed is upsetting for the engineers working on Flutter (many of
whom are volunteers, not that being paid to work on Flutter makes such comments
any less upsetting). Out of a respect for the team, and as required by our [code
of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md), we
of conduct](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md), we
ask that you avoid adding comments that are not actively helpful. There are other
venues if you want to complain without being constructive.
@ -42,11 +42,11 @@ being full of comments asking for updates and that makes finding useful informat
in a bug harder (an exception might be if you are participating in the triage process,
but even then consider reaching out to people directly if possible). If you believe
there could be information that has not been posted, ask on our Discord server instead
(see [[Chat]]).
(see [Chat](../Chat.md)).
### Issues are not always the best venue for discussions
Discussions within an issue should remain focused on the topic, specifically about what the filed issue is and how to solve it. Broader discussions are best suited to happen on Discord (see [[Chat]]) or in design docs using Google Docs (see [[Design Documents]]). This is because GitHub hides comments, doesn't have threading, notifications get lost in the swamp of other GitHub e-mails, etc.
Discussions within an issue should remain focused on the topic, specifically about what the filed issue is and how to solve it. Broader discussions are best suited to happen on Discord (see [Chat](../Chat.md)) or in design docs using Google Docs (see [Design Documents](../Design-Documents.md)). This is because GitHub hides comments, doesn't have threading, notifications get lost in the swamp of other GitHub e-mails, etc.
If you move to another tool for part of the discussion, remember to add a summary of the discussion and document any decisions that took place. This allows people following the issue to keep updated and continue to participate.
@ -76,7 +76,7 @@ can be copied and pasted into a test case.
To debug a problem, we will need to be able to reproduce it. The best way
to help us do that is to provide code, licensed according to [the BSD license
used by Flutter](https://github.com/flutter/flutter/blob/master/LICENSE), that
used by Flutter](https://github.com/flutter/flutter/blob/main/LICENSE), that
has been reduced as far as possible (such that removing anything further stops
showing the bug). Attach such a file or files to the issue itself.
@ -98,7 +98,7 @@ able to assist you will be reduced.
## Locking an issue
**Closed** issues that haven't received any activity in a [few weeks](https://github.com/flutter/flutter/blob/master/.github/lock.yml#L4)
**Closed** issues that haven't received any activity in a [few weeks](https://github.com/flutter/flutter/blob/main/.github/lock.yml#L4)
are automatically locked by a [bot](https://github.com/apps/lock). This is
done to encourage developers to file new bugs, instead of piling comments
on old ones.
@ -115,14 +115,14 @@ or might not be the same as this one".
If you are concerned that such an issue is not receiving its due
attention, see Escalating an Issue, described above. If you are
not already a contributor but would like to work on that issue,
consider reaching out on an appropriate [chat](https://github.com/flutter/flutter/wiki/Chat).
consider reaching out on an appropriate [chat](../Chat.md).
If you have a similar issue and are not sure if it is the same,
it is fine to file a new issue and linking it to the other issue.
Please avoid intentionally filing duplicates.
Very rarely, an issue gets locked because discussion has become
unproductive and has repeatedly violated the [Code of Conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md).
unproductive and has repeatedly violated the [Code of Conduct](https://github.com/flutter/flutter/blob/main/CODE_OF_CONDUCT.md).
## Priorities
@ -130,7 +130,7 @@ unproductive and has repeatedly violated the [Code of Conduct](https://github.co
**The [`P0`](https://github.com/flutter/flutter/labels/P0) label** indicates that the issue is one of the following:
* a build break, regression, or failure in an existing feature that prevents us from shipping the current build.
* an important item of technical debt that we want to fix promptly because it is impacting team velocity.
* an issue blocking, or about to block, a top-tier customer. (See [below](https://github.com/flutter/flutter/wiki/Issue-hygiene#customers) under "customers" for a definition of "top-tier customer".)
* an issue blocking, or about to block, a top-tier customer. (See [below](#customers) under "customers" for a definition of "top-tier customer".)
There are generally less than twenty-five P0 bugs (one GitHub search results page). If you find yourself assigning a P0 label to an issue, please be sure that there's a positive handoff between filing and a prospective owner for the issue.
@ -146,7 +146,7 @@ Issues at this level should be resolved in a matter of months and should have mo
**The [`P3`](https://github.com/flutter/flutter/labels/P3) label** indicates issues that we currently consider less important to the Flutter project. We use "thumbs-up" on these issues as a signal when discussing whether to promote them to P2 or higher based on demand. (Of course, this does not mean the issues are not important to _you_, just that we don't view them as the especially important for Flutter itself.)
Typically we would accept PRs for `P3` issues (assuming they follow our [style guide](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo) and follow our [other rules](https://github.com/flutter/flutter/wiki/Tree-hygiene)). Issues marked with the [`would require significant investment`](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22would+require+significant+investment%22) label may require more than just a PR, for example, adding support for a whole new platform will require a commitment to provide CI resources for build and test, and someone to own the maintenance of those systems.
Typically we would accept PRs for `P3` issues (assuming they follow our [style guide](../Style-guide-for-Flutter-repo.md) and follow our [other rules](../Tree-hygiene.md)). Issues marked with the [`would require significant investment`](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22would+require+significant+investment%22) label may require more than just a PR, for example, adding support for a whole new platform will require a commitment to provide CI resources for build and test, and someone to own the maintenance of those systems.
### When will my bug be fixed?
@ -154,13 +154,13 @@ Flutter is an open source project and many people contribute their time (or thei
To determine when a bug will be fixed, look at the issue.
If there's a recent status update on the issue, that is the best information we have about the bug. If there's a lot of comments on the issue, we try to link to the latest status from the top comment, so look there. (Please [don't _ask_](https://github.com/flutter/flutter/wiki/Issue-hygiene#do-not-add-me-too-or-same-or-is-there-an-update-comments-to-bugs) for updates, though.)
If there's a recent status update on the issue, that is the best information we have about the bug. If there's a lot of comments on the issue, we try to link to the latest status from the top comment, so look there. (Please [don't _ask_](#do-not-add-me-too-or-same-or-is-there-an-update-comments-to-bugs) for updates, though.)
If the issue is labeled with priorities `P0` or `P1`, or if the issue is assigned, we are likely to address it in the near term; we just need to find time.
Otherwise, we don't know when we're going to fix it. We may never get to it. In general, `P2` bugs are seen as more important than `P3` bugs. See the more detailed definitions of _priorities_ above.
_See also [[Popular issues]]._
_See also [Popular issues](../issue_hygiene/Popular-issues.md)._
### Escalating an issue that has the wrong priority
@ -169,7 +169,7 @@ your contact if you think the priority should be changed.
If you don't, consider finding like-minded developers to either implement
the feature as a team, or to fund hiring someone to work on the feature,
or to [mark the issue with a thumbs-up reaction](https://github.com/flutter/flutter/wiki/Issue-hygiene#thumbs-up-reactions).
or to [mark the issue with a thumbs-up reaction](#thumbs-up-reactions).
Please don't comment on an issue to indicate your interest. Comments should
be reserved for making progress on the issue.
@ -213,17 +213,17 @@ Common naming conventions for labels include:
- **`d: *`** - The green `d` ("documentation") labels are for organizing our documentation-related issues.
- **`dependency: *`** - Indicates the upstream team for issues that are blocked on some work from an upstream project (e.g. Skia, Dart).
- **`e: *`** - The `e` ("engine") prefix is for subsets of the Flutter engine ([flutter/engine](https://github.com/flutter/engine)).
- **`f: *`** - The `f` ("framework") prefix is for subsets of the Flutter framework ([flutter/flutter's packages/flutter/](https://github.com/flutter/flutter/tree/master/packages/flutter)).
- **`f: *`** - The `f` ("framework") prefix is for subsets of the Flutter framework ([flutter/flutter's packages/flutter/](https://github.com/flutter/flutter/tree/main/packages/flutter)).
- **`found in release: x.yy`** - Used for a series of labels that indicate which versions of Flutter an issue was found in.
- **`from: *`** - Labels that indicate where an issue originated (e.g. research, postmortems), if it wasn't filed organically.
- **`t: *`** - The `t` ("tool") prefix is for subsets of the Flutter tool ([flutter/flutter's packages/flutter_tools/](https://github.com/flutter/flutter/tree/master/packages/flutter_tools)).
- **`t: *`** - The `t` ("tool") prefix is for subsets of the Flutter tool ([flutter/flutter's packages/flutter_tools/](https://github.com/flutter/flutter/tree/main/packages/flutter_tools)).
- **`p: *`** - The `p` ("package") prefix is for specific packages ([flutter/packages](https://github.com/flutter/packages)). Light teal for packages and darker teal for plugins.
- **`platform-*`** - The `platform` prefix is for bugs that are specific to one or more platforms.
- **`r: *`** - The `r` ("resolution") prefix is used for labels that describe why an issue was closed.
### Adding labels
Labels are more or less free, so we can add them pretty easily. Please mention it to other team members first, so that they know what you are planning and can give feedback (please at a minimum mention it on `#hidden-chat` in our [[Chat]]). Please make sure labels use a consistent color and naming scheme (e.g. all the framework-related labels are blue and start with `f:`).
Labels are more or less free, so we can add them pretty easily. Please mention it to other team members first, so that they know what you are planning and can give feedback (please at a minimum mention it on `#hidden-chat` in our [Chat](../Chat.md)). Please make sure labels use a consistent color and naming scheme (e.g. all the framework-related labels are blue and start with `f:`).
Labels should be used for adding information to a bug. If you plan to use a label to find all instances of a particular topic (e.g. finding all PRs where someone wrote a design doc), be aware that there's no way to force people to label issues or PRs. You can, however, rely on automation to do it, for example we have a script that labels all PRs that affect the framework.
@ -250,7 +250,7 @@ and senior leads want resolved to the attention of the appropriate engineering
team.
The `customer: crowd` label is used to represent bugs that are affecting large
numbers of people; during initial [[Triage]], high-profile bugs get labeled in
numbers of people; during initial [Triage](https://github.com/flutter/flutter/wiki/Triage), high-profile bugs get labeled in
this way to bring them to the attention of the engineering team. "Large numbers"
is a judgement call. If dozens of people independently run into the same issue
and file a bug and we end up realizing that they're all duplicates of each other,
@ -281,7 +281,7 @@ We do not use GitHub milestones to track work.
Issues are typically self-assigned. Only assign a bug to someone else if
they have explicitly volunteered to do the task. If you don't have permissions
to assign yourself an issue you want to work on, don't worry about it, just
submit the PR (see [[Tree Hygiene]]).
submit the PR (see [Tree Hygiene](../Tree-hygiene.md)).
Only assign a bug to yourself when you are actively working on it
or scheduled to work on it. If you don't know when you'll be working
@ -329,14 +329,14 @@ If you have an idea that you would like to land, the recommended process is:
1. [File a bug](https://github.com/flutter/flutter/issues/new/choose) describing the problem.
2. Write a [design doc](https://flutter.dev/go/template) that references this problem and describes your solution.
3. Socialize your design on the bug you filed and on [[Chat]]. Collect feedback from various people.
4. Once you have received feedback, if it is mostly positive, implement your idea and submit it. See the [[Tree Hygiene]] wiki page for details on submitting PRs.
3. Socialize your design on the bug you filed and on [Chat](../Chat.md). Collect feedback from various people.
4. Once you have received feedback, if it is mostly positive, implement your idea and submit it. See the [Tree Hygiene](../Tree-hygiene.md) wiki page for details on submitting PRs.
### Every issue should be actionable
Avoid filing issues that are on vague topics without a clear problem description.
Please close issues that are not actionable. See [[Triage]] for more details.
Please close issues that are not actionable. See [Triage](https://github.com/flutter/flutter/wiki/Triage) for more details.
#### Issues should have clear steps to reproduce
@ -384,4 +384,4 @@ If you need to track some work item, you can file a bug and assign it to yoursel
When a test flakes, a P0 bug is automatically filed with the label [`team: flakes`](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22team%3A+flakes%22+sort%3Aupdated-asc). This issue should be investigated with all due haste, and a priority level should then be assigned to the issue. At any particular time, the most flaky tests should remain P0. However, flakes that are hard to pin down may be downgraded in priority (e.g. to P1). Please do not ignore the issue entirely, however, and make sure to close bugs once they are resolved, even if it's by magic.
_See also: [[Reducing test flakiness]]_
_See also: [Reducing test flakiness](https://github.com/flutter/flutter/wiki/Reducing-Test-Flakiness)_

View file

@ -86,36 +86,36 @@ To write a new iOS memory test case `some_memory_perf` and add it to Flutters
- Memory polling mechanism may incur additional memory overhead.
[manifest]: https://github.com/flutter/flutter/blob/master/dev/devicelab/manifest.yaml
[manifest]: https://github.com/flutter/flutter/blob/main/dev/devicelab/manifest.yaml
[tasks]: https://github.com/flutter/flutter/tree/master/dev/devicelab/bin/tasks
[tasks]: https://github.com/flutter/flutter/tree/main/dev/devicelab/bin/tasks
[class MemoryTest]: https://github.com/flutter/flutter/blob/51bb11f7cece47840a9ee6d6d43db97ab16b31df/dev/devicelab/lib/tasks/perf_tests.dart#L941
[complex layout memory manifest]: https://github.com/flutter/flutter/blob/7e41425d4af21dec7a7ff072a3ec1387859e32c8/dev/devicelab/manifest.yaml#L329
[complex layout memory task]: https://github.com/flutter/flutter/blob/master/dev/devicelab/bin/tasks/complex_layout_scroll_perf__memory.dart
[complex layout memory task]: https://github.com/flutter/flutter/blob/main/dev/devicelab/bin/tasks/complex_layout_scroll_perf__memory.dart
[complex layout memory main]: https://github.com/flutter/flutter/blob/master/dev/benchmarks/complex_layout/test_memory/scroll_perf.dart
[complex layout memory main]: https://github.com/flutter/flutter/blob/main/dev/benchmarks/complex_layout/test_memory/scroll_perf.dart
[fast scroll memory manifest]: https://github.com/flutter/flutter/blob/7e41425d4af21dec7a7ff072a3ec1387859e32c8/dev/devicelab/manifest.yaml#L837
[fast scroll memory task]: https://github.com/flutter/flutter/blob/master/dev/devicelab/bin/tasks/fast_scroll_large_images__memory.dart
[fast scroll memory task]: https://github.com/flutter/flutter/blob/main/dev/devicelab/bin/tasks/fast_scroll_large_images__memory.dart
[fast scroll memory main]: https://github.com/flutter/flutter/blob/master/dev/benchmarks/macrobenchmarks/test_memory/large_images.dart
[fast scroll memory main]: https://github.com/flutter/flutter/blob/main/dev/benchmarks/macrobenchmarks/test_memory/large_images.dart
[class DevToolsMemoryTest]: https://github.com/flutter/flutter/blob/7e41425d4af21dec7a7ff072a3ec1387859e32c8/dev/devicelab/lib/tasks/perf_tests.dart#L1138
[complex layout devtools memory manifest]: https://github.com/flutter/flutter/blob/7e41425d4af21dec7a7ff072a3ec1387859e32c8/dev/devicelab/manifest.yaml#L359
[complex layout devtools memory task]: https://github.com/flutter/flutter/blob/master/dev/devicelab/bin/tasks/complex_layout_scroll_perf__devtools_memory.dart
[complex layout devtools memory task]: https://github.com/flutter/flutter/blob/main/dev/devicelab/bin/tasks/complex_layout_scroll_perf__devtools_memory.dart
[large image changer manifest]: https://github.com/flutter/flutter/blob/7e41425d4af21dec7a7ff072a3ec1387859e32c8/dev/devicelab/manifest.yaml#L874
[large image changer task]: https://github.com/flutter/flutter/blob/master/dev/devicelab/bin/tasks/large_image_changer_perf_android.dart
[large image changer task]: https://github.com/flutter/flutter/blob/main/dev/devicelab/bin/tasks/large_image_changer_perf_android.dart
[Dart timeline]:https://flutter.dev/docs/development/tools/devtools/timeline
[large image changer manifest ios]: https://github.com/flutter/flutter/blob/7e41425d4af21dec7a7ff072a3ec1387859e32c8/dev/devicelab/manifest.yaml#L880
[large image changer task ios]: https://github.com/flutter/flutter/blob/master/dev/devicelab/bin/tasks/large_image_changer_perf_ios.dart
[large image changer task ios]: https://github.com/flutter/flutter/blob/main/dev/devicelab/bin/tasks/large_image_changer_perf_ios.dart

View file

@ -217,42 +217,42 @@ Tasks will be run automatically in the [devicelab], and the result is shown in [
Big congratulations if you've successfully finished all steps above! You just made a big contribution to Flutter's performance. Please also feel encouraged to improve this doc to help future contributors (which probably include a future yourself that would forget something above in a few months)!
<!-- Reference links below -->
[flutter_driver]: https://github.com/flutter/flutter/tree/master/packages/flutter_driver
[flutter_driver]: https://github.com/flutter/flutter/tree/main/packages/flutter_driver
[macrobenchmarks]: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks
[macrobenchmarks]: https://github.com/flutter/flutter/tree/main/dev/benchmarks/macrobenchmarks
[cocoon]: https://github.com/flutter/cocoon
[devicelab]: https://github.com/flutter/flutter/tree/master/dev/devicelab
[devicelab]: https://github.com/flutter/flutter/tree/main/dev/devicelab
[dev/devicelab/manifest.yaml]: https://github.com/flutter/flutter/tree/master/dev/devicelab/manifest.yaml
[dev/devicelab/manifest.yaml]: https://github.com/flutter/flutter/tree/main/dev/devicelab/manifest.yaml
[flutter_repo]: https://github.com/flutter/flutter
[macrobenchmarks/lib/src]: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks/lib/src
[macrobenchmarks/lib/src]: https://github.com/flutter/flutter/tree/main/dev/benchmarks/macrobenchmarks/lib/src
[macrobenchmarks/lib/common.dart]: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks/lib/common.dart
[macrobenchmarks/lib/common.dart]: https://github.com/flutter/flutter/tree/main/dev/benchmarks/macrobenchmarks/lib/common.dart
[macrobenchmarks/lib/main.dart]: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks/lib/main.dart
[macrobenchmarks/lib/main.dart]: https://github.com/flutter/flutter/tree/main/dev/benchmarks/macrobenchmarks/lib/main.dart
[`MacrobenchmarksApp`]: https://github.com/flutter/flutter/blob/94b7ff241e6e5445b7f30215a777eb4971311797/dev/benchmarks/macrobenchmarks/lib/main.dart#L24
[`HomePage`'s `ListView`]: https://github.com/flutter/flutter/blob/94b7ff241e6e5445b7f30215a777eb4971311797/dev/benchmarks/macrobenchmarks/lib/main.dart#L58
[macrobenchmarks/test_driver]: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks/test_driver
[macrobenchmarks/test_driver]: https://github.com/flutter/flutter/tree/main/dev/benchmarks/macrobenchmarks/test_driver
[macrobenchmarks/test_driver/run_app.dart]: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks/test_driver/run_app.dart
[macrobenchmarks/test_driver/run_app.dart]: https://github.com/flutter/flutter/tree/main/dev/benchmarks/macrobenchmarks/test_driver/run_app.dart
[macrobenchmarks/README.md]: https://github.com/flutter/flutter/blob/master/dev/benchmarks/macrobenchmarks/README.md
[macrobenchmarks/README.md]: https://github.com/flutter/flutter/blob/main/dev/benchmarks/macrobenchmarks/README.md
[dev/devicelab/bin/tasks]: https://github.com/flutter/flutter/tree/master/dev/devicelab/bin/tasks
[dev/devicelab/bin/tasks]: https://github.com/flutter/flutter/tree/main/dev/devicelab/bin/tasks
[dev/devicelab/lib/tasks/perf_tests.dart]: https://github.com/flutter/flutter/tree/master/dev/devicelab/lib/tasks/perf_tests.dart
[dev/devicelab/lib/tasks/perf_tests.dart]: https://github.com/flutter/flutter/tree/main/dev/devicelab/lib/tasks/perf_tests.dart
[flutter-dashboard]: https://flutter-dashboard.appspot.com/benchmarks.html
[e2e]: https://pub.dev/packages/e2e
[macrobenchmarks/test_driver/e2e_test.dart]: https://github.com/flutter/flutter/blob/master/dev/benchmarks/macrobenchmarks/test_driver/e2e_test.dart
[macrobenchmarks/test_driver/e2e_test.dart]: https://github.com/flutter/flutter/blob/main/dev/benchmarks/macrobenchmarks/test_driver/e2e_test.dart
[macrobenchmarks/test]: https://github.com/flutter/flutter/blob/master/dev/benchmarks/macrobenchmarks/test
[macrobenchmarks/test]: https://github.com/flutter/flutter/blob/main/dev/benchmarks/macrobenchmarks/test

View file

@ -86,7 +86,7 @@ For more details use the [documentation](https://github.com/flutter/web_installe
## Examples From Flutter Project
We already use Flutter Driver in many different places in Flutter Project. We have a smoke test running as a [Cirrus CI task](https://github.com/flutter/flutter/blob/master/.cirrus.yml#L291) in Flutter repo, which is also a great example for showing web_installers + flutter drive usage.
We already use Flutter Driver in many different places in Flutter Project. We have a smoke test running as a [Cirrus CI task](https://github.com/flutter/flutter/blob/main/.cirrus.yml#L291) in Flutter repo, which is also a great example for showing web_installers + flutter drive usage.
```
script:

View file

@ -9,15 +9,15 @@ We support several kinds of tests:
- Unit tests, e.g. using [`flutter_test`](https://api.flutter.dev/flutter/flutter_test/flutter_test-library.html). See below.
- Unit tests that use golden-file testing, comparing pixels.
See [[Writing a golden-file test for package:flutter]].
See [Writing a golden-file test for package:flutter](Writing-a-golden-file-test-for-package-flutter.md).
- End-to-end tests, e.g. using [`flutter_driver`](https://api.flutter.dev/flutter/flutter_driver/flutter_driver-library.html) and our [device lab](https://github.com/flutter/flutter/blob/master/dev/devicelab/README.md).
- End-to-end tests, e.g. using [`flutter_driver`](https://api.flutter.dev/flutter/flutter_driver/flutter_driver-library.html) and our [device lab](https://github.com/flutter/flutter/blob/main/dev/devicelab/README.md).
Our bots run on our [test and build infrastructure](https://github.com/flutter/flutter/blob/master/dev/bots/README.md).
Our bots run on our [test and build infrastructure](https://github.com/flutter/flutter/blob/main/dev/bots/README.md).
## Running unit tests
Flutter tests use the `flutter_test` package ([source](https://github.com/flutter/flutter/tree/master/packages/flutter_test), [API documentation](https://api.flutter.dev/flutter/flutter_test/flutter_test-library.html)),
Flutter tests use the `flutter_test` package ([source](https://github.com/flutter/flutter/tree/main/packages/flutter_test), [API documentation](https://api.flutter.dev/flutter/flutter_test/flutter_test-library.html)),
which provides flutter-specific extensions on top of the [Dart `test` package](https://pub.dartlang.org/packages/test).
To automatically find all files named `*_test.dart` inside a package's `test/` subdirectory, and
@ -45,7 +45,7 @@ before the test runs.
To run analysis and all the tests for the entire Flutter repository, the same way that Cirrus
runs them, run `dart dev/bots/test.dart` and `dart --enable-asserts dev/bots/analyze.dart`.
If you've built your own flutter engine (see [[Setting up the Engine development environment]]), you
If you've built your own flutter engine (see [Setting up the Engine development environment](../../engine/dev/Setting-up-the-Engine-development-environment.md)), you
can pass `--local-engine` to change what flutter shell `flutter test` uses. For example,
if you built an engine in the `out/host_debug_unopt` directory, you can use:
@ -58,9 +58,9 @@ flutter test \
to run the tests in the locally built engine. Note that in this case you need to specify `host_debug_unopt`
as both arguments.
To learn how to see how well tested the codebase is, see [[Test coverage for package:flutter]].
To learn how to see how well tested the codebase is, see [Test coverage for package:flutter](Test-coverage-for-package-flutter.md).
_See also: [[Flutter Test Fonts]]_
_See also: [Flutter Test Fonts](Flutter-Test-Fonts.md)_
## Running device lab tests locally
@ -118,8 +118,8 @@ The following is an example of what running the local engine command might look
The above command would use the local Flutter engine located at `/Users/myname/flutter/engine` to execute the `external_ui_integration_test` test on an Android emulator, which is why the `android_debug_unopt_x86` version of the engine is used.
Note that some tests may require `profile` mode instead of `debug` mode when running with local engine. Make sure to pass in the correct local engine. See [Compiling the engine](https://github.com/flutter/flutter/wiki/Compiling-the-engine) for more details.
Note that some tests may require `profile` mode instead of `debug` mode when running with local engine. Make sure to pass in the correct local engine. See [Compiling the engine](../../engine/dev/Compiling-the-engine.md) for more details.
## For the engine
See the [[Testing the engine]] wiki.
See the [Testing the engine](../../engine/testing/Testing-the-engine.md) wiki.

View file

@ -227,4 +227,4 @@ When writing tests, think about the developer who will read this test 6 months f
# See also
- [Flutter Test Fonts](https://github.com/flutter/flutter/wiki/Flutter-Test-Fonts)
- [Flutter Test Fonts](Flutter-Test-Fonts.md)

View file

@ -5,16 +5,14 @@ _(This page is referenced by comments in the Flutter codebase.)_
Golden file tests for `package:flutter` use [Flutter Gold](https://flutter-gold.skia.org/?query=source_type%3Dflutter) for baseline and version management of golden files. This allows for golden file testing on Linux, Windows, MacOS and Web, which accounts for the occasional subtle rendering differences between these platforms.
## Index
- [Known Issues](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter#known-issues)
- [Build Breakage](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter#build-breakage)
- [Creating a New Golden File Test](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package%3Aflutter#creating-a-new-golden-file-test)
- [Updating a Golden File Test](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package%3Aflutter#updating-a-golden-file-test
)
- [Flutter Gold Login](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package%3Aflutter#flutter-gold-login
)
- [`flutter-gold` Check](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter#flutter-gold-check)
- [`reduced-test-set` tag](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter#reduced-test-set-tag)
- [Troubleshooting](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter#troubleshooting)
- [Known Issues](#known-issues)
- [Build Breakage](#build-breakage)
- [Creating a New Golden File Test](#creating-a-new-golden-file-test)
- [Updating a Golden File Test](#updating-a-golden-file-test)
- [Flutter Gold Login](#flutter-gold-login)
- [`flutter-gold` Check](#flutter-gold-check)
- [`reduced-test-set` tag](#reduced-test-set-tag)
- [Troubleshooting](#troubleshooting)
## Known Issues
@ -30,6 +28,8 @@ If you would like to instantly invalidate all prior renderings, changing the nam
If the Flutter build is broken due to a golden file test failure, this typically means an image change has landed without being triaged. Golden file images should be triaged in pre-submit before a change lands (as described in the steps below). If this process is not followed, a test with an unapproved golden file image will fail in post-submit testing. This will present in the following error message:
<!-- TODO(Piinks): Update this error message in the framework. -->
```
Skia Gold received an unapproved image in post-submit
testing. Golden file images in flutter/flutter are triaged
@ -91,7 +91,7 @@ And thats it! Your new golden file(s) will be checked in as the baseline(s) f
## Flutter Gold Login
Triage permission is currently restricted to members of *flutter-hackers*. For more information, see [Contributor Access](https://github.com/flutter/flutter/wiki/Contributor-access).
Triage permission is currently restricted to members of *flutter-hackers*. For more information, see [Contributor Access](../Contributor-access.md).
Once you have been added as an authorized user for Flutter Gold, you can log in through the [homepage of the Flutter Gold dashboard](https://flutter-gold.skia.org/) and proceed to triage your image results under [Changelists](https://flutter-gold.skia.org/changelists).
## `flutter gold` Check