CONTRIBUTING.md 12.6 KB
Newer Older
Adam Barth's avatar
Adam Barth committed
1 2 3 4 5
Contributing to Flutter
=======================

[![Build Status](https://travis-ci.org/flutter/flutter.svg)](https://travis-ci.org/flutter/flutter)

6 7
_See also: [Flutter's code of conduct](https://flutter.io/design-principles/#code-of-conduct)_

Adam Barth's avatar
Adam Barth committed
8 9 10 11 12
Things you will need
--------------------

 * Linux or Mac OS X. (Windows is not yet supported.)
 * git (used for source version control).
13
 * An IDE. We recommend [IntelliJ with the Flutter plugin](https://flutter.io/intellij-ide/).
Adam Barth's avatar
Adam Barth committed
14 15 16
 * An ssh client (used to authenticate with GitHub).
 * Python (used by some of our tools).
 * The Android platform tools (see [Issue #55](https://github.com/flutter/flutter/issues/55)
Adam Barth's avatar
Adam Barth committed
17
   about downloading the Android platform tools automatically).
Ian Hickson's avatar
Ian Hickson committed
18
   _If you're also working on the Flutter engine, you can use the
Adam Barth's avatar
Adam Barth committed
19
   copy of the Android platform tools in
Ian Hickson's avatar
Ian Hickson committed
20
   `.../engine/src/third_party/android_tools/sdk/platform-tools`._
Adam Barth's avatar
Adam Barth committed
21 22 23 24 25 26 27
   - 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
28 29 30
   git, ssh, and python are installed. Ensure that `adb`
   (from the Android platform tools) is in your path (e.g.,
   that `which adb` prints sensible output).
Adam Barth's avatar
Adam Barth committed
31 32 33 34 35 36 37 38 39 40 41 42
 * 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.)
 * Add this repository's `bin` directory to your path. That will let you use the
43
   `flutter` command in this directory more easily.
44 45 46
 * Run `flutter update-packages` 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.
Adam Barth's avatar
Adam Barth committed
47 48 49 50 51 52

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
53
downloaded, and use `flutter run`. Make sure you have a device connected over
Adam Barth's avatar
Adam Barth committed
54 55
USB and debugging enabled on that device.

56 57
 * `cd examples/hello_world`
 * `flutter run`
Adam Barth's avatar
Adam Barth committed
58 59 60

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
61
example, to run the `widgets/spinning_square.dart` example in the [examples/layers](examples/layers)
Adam Barth's avatar
Adam Barth committed
62
directory on a connected Android device, from that directory you would run:
63
`flutter run -t widgets/spinning_square.dart`
Adam Barth's avatar
Adam Barth committed
64 65 66 67 68 69 70

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](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.

71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
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
Offset from `dart:ui`.

For a one-off, use `flutter analyze --flutter-repo`. This uses the `.analysis_options_repo` file
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 `--dartdocs`.

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.


Adam Barth's avatar
Adam Barth committed
92 93 94
Running the tests
-----------------

95
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:
Adam Barth's avatar
Adam Barth committed
96

97
 * `cd examples/stocks`
98
 * `flutter test`
Adam Barth's avatar
Adam Barth committed
99

100 101
Individual tests can also be run directly, e.g. `flutter test lib/my_app_test.dart`

102
Flutter tests use [package:flutter_test](https://github.com/flutter/flutter/tree/master/packages/flutter_test) which provides flutter-specific extensions on top of [package:test](https://pub.dartlang.org/packages/test).
Adam Barth's avatar
Adam Barth committed
103

xster's avatar
xster committed
104
`flutter test` runs tests inside the flutter shell. To debug tests in Observatory, use the `--start-paused` option to start the test in a paused state and wait for connection from a debugger. This option lets you set breakpoints before the test runs.
105

106
To run all the tests for the entire Flutter repository, the same way that Travis runs them, run `dart dev/bots/test.dart`.
107

108 109 110
If you've built [your own flutter engine](#working-on-the-engine-and-the-framework-at-the-same-time), 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.
Adam Barth's avatar
Adam Barth committed
111

112
Flutter tests are headless, you won't see any UI. You can use
Ian Hickson's avatar
Ian Hickson committed
113 114
`print` to generate console output or you can interact with the DartVM
via observatory at [http://localhost:8181/](http://localhost:8181/).
Adam Barth's avatar
Adam Barth committed
115 116 117 118

Adding a test
-------------

119
To add a test to the Flutter package, create a file whose name
120 121
ends with `_test.dart` in the `packages/flutter/test` directory. The
test should have a `main` function and use the `test` package.
Adam Barth's avatar
Adam Barth committed
122

123 124 125 126 127 128 129 130 131 132 133 134
Working with flutter tools
--------------------------

The flutter tools itself is built when you run `flutter` for the first time and each time
you run `flutter upgrade`. If you want to alter and re-test the tool's behavior itself,
locally commit your tool changes in git and the tool will be rebuilt from Dart sources
in `packages/flutter_tools` the next time you run `flutter`.

flutter_tools' tests run inside the Dart command line VM rather than in the
flutter shell. To run the test:

* `cd packages/flutter_tools`
xster's avatar
xster committed
135
* `dart --checked test/all.dart`
136 137 138 139 140

The pre-built flutter tool runs in release mode with the observatory off by default.
To enable debugging mode and the observatory on the `flutter` tool, uncomment the
`FLUTTER_TOOL_ARGS` line in the `bin/flutter` shell script.

Adam Barth's avatar
Adam Barth committed
141 142 143 144 145
Contributing code
-----------------

We gladly accept contributions via GitHub pull requests.

146 147 148 149 150 151
Please peruse our
[style guides](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo) and
[design principles](https://flutter.io/design-principles/) before
working on anything non-trivial. These guidelines are intended to
keep the code consistent and avoid common pitfalls.

Adam Barth's avatar
Adam Barth committed
152 153 154 155
To start working on a patch:

 * `git fetch upstream`
 * `git checkout upstream/master -b name_of_your_branch`
156
 * Hack away.
Ian Hickson's avatar
Ian Hickson committed
157
 * `git commit -a -m "<your informative commit message>"`
Adam Barth's avatar
Adam Barth committed
158 159 160 161 162 163 164 165 166 167
 * `git push origin name_of_your_branch`

To send us a pull request:

* `git pull-request` (if you are using [Hub](http://github.com/github/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.

168 169
Once you've gotten an LGTM from a project maintainer, submit your changes to the
`master` branch using one of the following methods:
170

171
* Wait for one of the project maintainers to submit it for you.
172 173 174 175
* 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)

Adam Barth's avatar
Adam Barth committed
176 177 178 179 180 181
You must complete the
[Contributor License Agreement](https://cla.developers.google.com/clas).
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](AUTHORS) file.

182 183 184
We grant commit access to people who have gained our trust and demonstrated
a commitment to Flutter.

185 186 187 188 189 190 191 192
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](https://coveralls.io/github/flutter/flutter?branch=master).
You can download our current coverage data from cloud storage and visualize it
in Atom as follows:

193
 * Install [Atom](https://atom.io/).
194
 * Install the [lcov-info](https://atom.io/packages/lcov-info) package for Atom.
195 196 197 198 199 200 201
 * Open the `packages/flutter` folder in Atom.
 * Open a Dart file in the `lib` directory an type `Ctrl+Alt+C` to bring up the
   coverage data.

If you don't see any coverage data, check that you have an `lcov.info` file in
the `packages/flutter/coverage` directory. It should have been downloaded by the
`flutter update-packages` command you ran previously.
202

203 204 205 206 207 208 209 210 211 212 213
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.
 * Run `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 `flutter update-packages`.

214 215 216
See [issue 4719](https://github.com/flutter/flutter/issues/4719) for ideas about
how to improve this workflow.

Adam Barth's avatar
Adam Barth committed
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
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](https://github.com/flutter/engine) 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](https://github.com/flutter/engine/blob/master/CONTRIBUTING.md)
   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
237 238
   (e.g., `out/host_debug_unopt`). To run examples on Android, build one of the
   Android configurations (e.g., `out/android_debug_unopt`).
Adam Barth's avatar
Adam Barth committed
239

Ian Hickson's avatar
Ian Hickson committed
240
You should now be able to run the tests against your locally built
241 242 243
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` tool:
Adam Barth's avatar
Adam Barth committed
244

245
 * `flutter run --local-engine=android_debug_unopt`
Adam Barth's avatar
Adam Barth committed
246 247 248 249

Making a breaking change to the engine
--------------------------------------

krisgiesing's avatar
krisgiesing committed
250
If you make a breaking change to the engine, you'll need to land your change in a
Adam Barth's avatar
Adam Barth committed
251 252 253 254 255 256 257 258 259 260 261 262 263 264
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](https://github.com/flutter/engine/wiki/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](packages/flutter/pubspec.yaml).
   After changing the `pubspec.yaml` file, you'll need to run
Jason Simmons's avatar
Jason Simmons committed
265
   `./dev/update_packages.dart` to update all the packages in this repository to
Adam Barth's avatar
Adam Barth committed
266 267 268
   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.