Contributing to Flutter

Build Status

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 Dart SDK (see Issue #54 about downloading the Dart SDK automatically).
  • The Android platform tools (see Issue #55 about downloading the Android platform tools automatically):
    • Mac: brew install android-platform-tools
    • Linux: 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 dart, pub, and adb (from the Dart SDK and the Android platform tools) are in your path (e.g., that which dart and which adb print sensible output).
  • Fork https://github.com/flutter/flutter into 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 git@github.com:<your_name_here>/flutter.git
  • cd flutter
  • git remote add upstream git@github.com:flutter/flutter.git (So that you fetch from the master repository, not your clone, when running git fetch et al.)
  • Run ./dev/update_packages.py This will fetch all the Dart packages that Flutter depends on. You can replicate what this script does by running pub get in each directory that contains a pubspec.yaml file.
  • Add this repository's bin directory to your path. That will let you use the flutter command in this directory more easily.

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 start. Make sure you have a device connected over USB and debugging enabled on that device.

  • cd examples/hello_world; flutter start

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 tabs.dart example in the examples/widgets directory on a connected Android device, from that directory you would run:

  • flutter start -t tabs.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 examples subdirectories.

Running the tests

Each package in the packages directory has its own suite of tests based on the test package. To run the tests for a given package, for example, the newton package, use the following commands:

  • cd packages/newton
  • pub run test

Testing the flutter package is currently a bit harder because we don‘t yet support testing the flutter package with pre-built binaries. To test the package, you’ll need to follow the instructions below for working with this repository and the Flutter engine repository simultaneously and then run the following command:

  • ./dev/run_tests --debug

Creating a workflow for running the test with a prebuilt binary is Issue #56. If you want to run a single test individually:

  • ./dev/run_tests --debug test/harness/trivial_test.dart

Note: The tests are headless, you won't see any UI. You can use print to generate console output or you can interact with the DartVM via observatory at http://localhost:8181/.

Adding a test

To add a test, simply create a file whose name ends with _test.dart in the packags/unit/test directory. The test should have a main function and use the test package.

Contributing code

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. Please peruse our style guides and design principles before working on anything non-trivial. These guidelines are intended to keep the code consistent and avoid common pitfalls.
  • git commit -a -m "<your brief but 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/flutter and click the “Compare & pull request” button

Please make sure all your checkins have detailed commit messages explaining the patch. If you made multiple commits for a single pull request, either make sure each one has a detailed message explaining that specific commit, or squash your commits into one single checkin with a detailed message before sending the pull request.

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.

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.

  1. Follow the instructions above for creating a working copy of this repository.

  2. Follow the contributing instructions for the engine repository to create a working copy of the engine. When you create the .gclient file for the engine, be sure to create it in a directory named engine that is a sibling of the directory in which you cloned this repository. For example, if you cloned this repository into the /foo/bar/flutter directory, you should create the .gclient file in the /foo/bar/engine directory. The actual code from the engine repository will end up in /foo/bar/engine/src because gclient creates a src directory underneath the directory that contains the .gclient file.

  3. To run tests on your host machine, build one of the host configurations (e.g., out/Debug). To run examples on Android, build one of the Android configurations (e.g., out/android_Debug).

You should now be able to run the tests against your locally built engine using the ./dev/run_tests script. To run one of the examples on your device using your locally built engine, use the --engine-src-path option to the flutter tool:

  • flutter start --engine-src-path /foo/bar/engine/src

Eventually, the --local-build flag for the flutter command will automatically set the correct engine src path (see Issue #57).

Making a breaking change to the engine

If you make a breaking change to the engine, you'll need to land you change in a few steps:

  1. Land your change in the engine repository.

  2. 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).

  3. Land a change that update our dependency on the sky_engine and sky_services packages 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.yaml file, you'll need to run ./dev/update_packages.py to 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.