Contributing to Flutter
See also: Flutter's code of conduct
Things you will need
- Linux or Mac OS X. (Windows is not yet supported.)
- git (used for source version control).
- An IDE. We recommend Atom.
- An ssh client (used to authenticate with GitHub).
- Python (used by some of our tools).
- The Android platform tools (see Issue #55
about downloading the Android platform tools automatically).
If you're also working on the Flutter engine, you can use the
copy of the Android platform tools in
brew install android-platform-tools
sudo apt-get install android-tools-adb
Getting the code and configuring your environment
- Ensure all the dependencies described in the previous section, in particular
git, ssh, and python are installed. Ensure that
adb(from the Android platform tools) is in your path (e.g., that
which adbprints sensible output).
https://github.com/flutter/flutterinto your own GitHub account. If you already have a fork, and are now installing a development environment on a new machine, make sure you've updated your fork so that you don't use stale configuration options from long ago.
- If you haven't configured your machine with an SSH key that's known to github then follow the directions here: https://help.github.com/articles/generating-ssh-keys/.
git clone email@example.com:<your_name_here>/flutter.git
git remote add upstream firstname.lastname@example.org:flutter/flutter.git(So that you fetch from the master repository, not your clone, when running
git fetchet al.)
- Add this repository's
bindirectory to your path. That will let you use the
fluttercommand in this directory more easily.
flutter update-packagesThis will fetch all the Dart packages that Flutter depends on. You can replicate what this script does by running
pub getin each directory that contains a
Running the examples
To run an example with a prebuilt binary from the cloud, switch to that
example's directory, run
pub get to make sure its dependencies have been
downloaded, and use
flutter run. Make sure you have a device connected over
USB and debugging enabled on that device.
You can also specify a particular Dart file to run if you want to run an example
that doesn't have a
lib/main.dart file using the
-t command-line option. For
example, to run the
widgets/spinning_square.dart example in the examples/layers
directory on a connected Android device, from that directory you would run:
flutter run -t widgets/spinning_square.dart
When running code from the examples directory, any changes you make to the
example code, as well as any changes to Dart code in the
packages/flutter directory and subdirectories, will
automatically be picked when you relaunch the app. You can do the same for your
own code by mimicking the
pubspec.yaml files in the
Running the analyzer
When editing Flutter code, it's important to check the code with the analyzer. There are two
main ways to run it. In either case you will want to run
flutter update-packages --upgrade
first, or you will get version conflict issues or bogus error messages about core clases like
For a one-off, use
flutter analyze --flutter-repo. This uses the
at the root of the repository for its configuration.
For continuous analysis, use
flutter analyze --flutter-repo --watch. This uses normal
.analysis_options files, and they can differ from package to package.
If you want to see how many members are missing dartdocs, you should use the first option,
providing the additional command
If you omit the
--flutter-repo option you may end up in a confusing state because that will
assume you want to check a single package and the flutter repository has several packages.
Running the tests
To automatically find all files named
_test.dart inside a package's
test/ subdirectory, and run them inside the flutter shell as a test, use the
flutter test command, e.g:
Individual tests can also be run directly, e.g.
flutter test lib/my_app_test.dart
flutter test runs tests inside the flutter shell. Some packages inside the flutter repository can be run inside the dart command line VM as well as the flutter shell,
packages/flutter_tools is one such example:
To run all the tests for the entire Flutter repository, the same way that Travis runs them, run
If you've built your own flutter engine, 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 pass
--local-engine=host_debug_unopt to run the tests in that engine.
Flutter tests are headless, you won't see any UI. You can use
Adding a test
To add a test to the Flutter package, create a file whose name
_test.dart in the
packages/flutter/test directory. The
test should have a
main function and use the
We gladly accept contributions via GitHub pull requests.
To start working on a patch:
git fetch upstream
git checkout upstream/master -b name_of_your_branch
- Hack away.
git commit -a -m "<your informative commit message>"
git push origin name_of_your_branch
To send us a pull request:
git pull-request(if you are using Hub) or go to
https://github.com/flutter/flutterand click the "Compare & pull request" button
Please make sure all your checkins have detailed commit messages explaining the patch.
Once you've gotten an LGTM from a project maintainer, submit your changes to the
master branch using one of the following methods:
- Wait for one of the project maintainers to submit it for you.
- Click the green "Merge pull request" button on the GitHub UI of your pull request (requires commit access)
git push upstream name_of_your_branch:master(requires commit access)
You must complete the Contributor License Agreement. You can do this online, and it only takes a minute. If you've never submitted code before, you must add your (or your organization's) name and contact info to the AUTHORS file.
We grant commit access to people who have gained our trust and demonstrated a commitment to Flutter.
Tools for tracking an improving test coverage
We strive for a high degree of test coverage for the Flutter framework. We use Coveralls to track our test coverage. You can download our current coverage data from cloud storage and visualize it in Atom as follows:
- Install the lcov-info package for Atom.
- Open the
packages/flutterfolder in Atom.
- Open a Dart file in the
libdirectory an type
Ctrl+Alt+Cto bring up the coverage data.
If you don't see any coverage data, check that you have an
lcov.info file in
packages/flutter/coverage directory. It should have been downloaded by the
flutter update-packages command you ran previously.
If you want to iterate quickly on improving test coverage, consider using this workflow:
- Open a file and observe that some line is untested.
- Write a test that exercises that line.
flutter test --merge-coverage path/to/your/test_test.dart.
- After the test passes, observe that the line is now tested.
This workflow merges the coverage data from this test run with the base coverage
data downloaded by
See issue 4719 for ideas about how to improve this workflow.
Working on the engine and the framework at the same time
You can work both with this repository (flutter.git) and the Flutter engine repository at the same time using the following steps.
Follow the instructions above for creating a working copy of this repository.
Follow the contributing instructions for the engine repository to create a working copy of the engine. When you create the
.gclientfile for the engine, be sure to create it in a directory named
enginethat is a sibling of the directory in which you cloned this repository. For example, if you cloned this repository into the
/foo/bar/flutterdirectory, you should create the
.gclientfile in the
/foo/bar/enginedirectory. The actual code from the engine repository will end up in
srcdirectory underneath the directory that contains the
To run tests on your host machine, build one of the host configurations (e.g.,
out/host_debug_unopt). To run examples on Android, build one of the Android configurations (e.g.,
You should now be able to run the tests against your locally built
engine using the
flutter test --local-engine=host_debug_unopt command. To run
one of the examples on your device using your locally built engine, use the
--local-engine=android_debug_unopt option to the
flutter run --local-engine=android_debug_unopt
Making a breaking change to the engine
If you make a breaking change to the engine, you'll need to land your change in a few steps:
Land your change in the engine repository.
Publish a new version of the engine that contains your change. See the engine's release process for instructions about how to publish a new version of the engine. Publishing a new version is important in order to not break folks using prebuilt binaries in their workflow (e.g., our customers).
Land a change that update our dependency on the
sky_servicespackages to point to the new version of the engine that you just published. These dependencies are defined by packages/flutter/pubspec.yaml. After changing the
pubspec.yamlfile, you'll need to run
./dev/update_packages.dartto update all the packages in this repository to see the new dependency. As part of landing this change, you should make whatever other changes are needed in this repository to account for your breaking change.