Add a CONTRIBUTING.md
This document describes the workflow for contributing code to this repository.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3892e8b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,190 @@
+Contributing to Flutter
+=======================
+
+[](https://travis-ci.org/flutter/flutter)
+
+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](https://github.com/flutter/engine/wiki/Using-Atom-with-Flutter).
+ * An ssh client (used to authenticate with GitHub).
+ * Python (used by some of our tools).
+ * The Dart SDK (see [Issue #54](https://github.com/flutter/flutter/issues/54)
+ about downloading the Dart SDK automatically).
+ - [https://www.dartlang.org/downloads/archive/](https://www.dartlang.org/downloads/archive/)
+ * The Android platform tools (see [Issue #55](https://github.com/flutter/flutter/issues/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](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](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](#working-on-the-engine-and-the-framework-at-the-same-time)
+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](https://github.com/flutter/flutter/issues/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/](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](https://github.com/flutter/engine/blob/master/sky/specs/style-guide.md)
+ and [design principles](https://github.com/flutter/engine/blob/master/sky/specs/design.md)
+ 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](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.
+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](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.
+
+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
+ (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](https://github.com/flutter/flutter/issues/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](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
+ `./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.
diff --git a/README.md b/README.md
index cfad87b..4d8e9ad 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,17 @@
Flutter is optimized for today's, and tomorrow's, mobile devices. We are
focused on low-latency input and high frame rates on Android and iOS.
+_Flutter is an early-stage open-source project._ We are still missing core
+features like accessibility, text input, localization, and more. However,
+you can build demos and examples today. We hope you try it out and send
+us [feedback](mailto:flutter-dev@googlegroups.com).
+
- For information about using Flutter to build apps, please see
the [getting started guide](http://flutter.io/getting-started/).
+- For information about contributing code to Flutter itself, please see
+ [CONTRIBUTING.md](CONTRIBUTING.md).
+
Community
---------
diff --git a/dev/run_tests b/dev/run_tests
index 9c5f729..ff0ff36 100755
--- a/dev/run_tests
+++ b/dev/run_tests
@@ -17,13 +17,13 @@
def main():
parser = argparse.ArgumentParser(description='Runs Flutter unit tests')
- parser.add_argument('--engine-dir', default=DEFAULT_ENGINE_DIR)
+ parser.add_argument('--engine-src-path', default=DEFAULT_ENGINE_DIR)
parser.add_argument('--config', default='Debug')
parser.add_argument('--debug', dest='config', action='store_const', const='Debug')
parser.add_argument('--release', dest='config', action='store_const', const='Release')
args, remaining = parser.parse_known_args()
- build_dir = os.path.join(os.path.abspath(args.engine_dir), 'out', args.config)
+ build_dir = os.path.join(os.path.abspath(args.engine_src_path), 'out', args.config)
if not remaining:
for root, dirs, files in os.walk(TESTS_DIR):
diff --git a/packages/flutter_tools/lib/src/commands/flutter_command_runner.dart b/packages/flutter_tools/lib/src/commands/flutter_command_runner.dart
index f4659be..4895fb0 100644
--- a/packages/flutter_tools/lib/src/commands/flutter_command_runner.dart
+++ b/packages/flutter_tools/lib/src/commands/flutter_command_runner.dart
@@ -29,7 +29,7 @@
'shell commands executed.');
argParser.addOption('package-root',
help: 'Path to your packages directory.', defaultsTo: 'packages');
- argParser.addOption('flutter-root',
+ argParser.addOption('flutter-root', hide: true,
help: 'The root directory of the Flutter repository.');
argParser.addOption('android-device-id',
help: 'Serial number of the target Android device.');
@@ -50,11 +50,12 @@
'on iOS devices and simulators. Not normally required.');
argParser.addFlag('local-build',
negatable: false,
+ hide: true,
help:
'Automatically detect your engine src directory from an overridden Flutter package. '
'Useful if you are building Flutter locally and are using a dependency_override for'
'the Flutter package that points to your engine src directory.');
- argParser.addOption('engine-src-path', hide: true,
+ argParser.addOption('engine-src-path',
help:
'Path to your engine src directory, if you are building Flutter locally. '
'Ignored if neither debug nor release is set. Not normally required.');
diff --git a/travis/test.sh b/travis/test.sh
index de9a355..d2fd711 100755
--- a/travis/test.sh
+++ b/travis/test.sh
@@ -6,4 +6,4 @@
(cd packages/flx; pub global run tuneup check; pub run test -j1)
(cd packages/newton; pub global run tuneup check; pub run test -j1)
-./dev/run_tests --engine-dir bin/cache/travis
+./dev/run_tests --engine-src-path bin/cache/travis
