Added HACKING.md to observatory

runtime/observatory/HACKING.md

Index: runtime/observatory/HACKING.md
diff --git a/runtime/observatory/HACKING.md b/runtime/observatory/HACKING.md
new file mode 100644
index 0000000000000000000000000000000000000000..f89056599beb8e8992c5979c88cf886e94eee891
--- /dev/null
+++ b/runtime/observatory/HACKING.md
@@ -0,0 +1,169 @@
+# Hacking Observatory
+
+These instructions will guide you through the Observatory development and
+testing workflow.
+
+## SDK Setup & Build
+Getting ready to start.
+
+Before starting hacking observatory follow [the instructions][1] to have a

[Cutch, 2016/06/20 14:47:01]

how about [instructions](http://....) for this and all the links?

[cbernaschina, 2016/06/20 16:10:11]

The [...][...] version allows to reuse links and to force a tooltip.

Anyway it is just a personal preference.

+working environment in which you are able to build and test the Dart SDK.
+
+## Run existing tests
+Before hacking Observatory let's run the existing Observatory tests.
+
+From the root of the sdk repository run:
+```
+$ ./tools/test.py -mrelease service

[Cutch, 2016/06/20 14:47:01]

We recommend people use the debug mode for running tests.

Also, they will need to have built the debug mode first.

[cbernaschina, 2016/06/20 16:10:11]

Done.

+```
+
+## Develop with Dartium ~ Suggested
+If you want to avoid to trigger a new compilation to JavaScript for each edit

[Cutch, 2016/06/20 14:47:01]

If you want to avoid triggering a ...

[cbernaschina, 2016/06/20 16:10:11]

Done.

+you do, you can use a modified version of Chromium named Dartium that will
+interpret you dart code directly.
+
+You can obtain Dartium in two different ways:

[Cutch, 2016/06/20 14:47:01]

Move the dartium download up to the top in the setup & build section.

[cbernaschina, 2016/06/20 16:10:11]

Done.

+1. [Download the binaries][2]
+2. [Build Dartium from the source code][3]
+
+## Serve Observatory
+In order to avoid a complete build of the sdk for each change you do to

[Cutch, 2016/06/20 14:47:01]

How about:

"Observatory is built as part of building the sdk, but when working on
Observatory we recommend that you use pub serve so you can avoid the overhead of
building the sdk for each change"

[cbernaschina, 2016/06/20 16:10:11]

Done.

+Observatory, we are going to __serve__ it directly.
+
+Use __pub__ to __serve__ Observatory:
+```
+[...]/runtime/observatory$ pub serve
+```
+
+## Open Observatory
+You can open the development version of Observatory from
+Chrome/Chromium/__Dartium__ by navigating to [localhost:8080][4]
+
+Every change you make to the Observatory source code will be visible by simply
+__refreshing__ the page in the browser.
+
+## Connect to a VM
+Start a Dart VM with the ``--observe`` flag (as explained in the
+[get started guide][5]) and connect your Observatory instance to that VM.

[Cutch, 2016/06/20 14:47:01]

Let's provide a sample script here:


```dart
import 'dart:async';

main() {
  new Timer.periodic(const Duration(seconds: 1.....
}
```

And then give the example command line:

$ dart --observe scrpit.dart

[cbernaschina, 2016/06/20 16:10:11]

Done.

+
+## Code Reviews
+The development workflow of Dart (and Observatory) is based on code reviews.
+
+Follow the [code review instructions][6] to be able to successfully submit your
+code.
+
+The main reviewers for Observatory related CLs are:
+  - turnidge
+  - johnmccutchan
+  - rmacnak
+
+## Write a new service test
+All the service tests are located in the ```tests/service``` folder.
+Test file names follow the convention ```<description>_test.dart```
+(e.g. ```a_brief_description_test.dart```).
+
+The test is generally structured in the following way.
+```dart
+import 'package:test/test.dart';
+
+main() {
+  // Some code that you need to test.
+  var a = 1 + 2;
+
+  // Some assertions to check the results.
+  expect(a, equal(3));
+}
+```
+See the official [test library][7] instructions;
+
+The ```test_helper.dart``` file expose some functions that allow to run a part
+of the code into another __VM__.
+
+To test synchronous operations:
+```dart
+import 'test_helper.dart';
+
+code() {
+  // Write the code you want to be execute into another VM.
+}
+
+var tests = [
+  // A series of tests that you want to run against the above code.
+  (Isolate isolate) async {
+    await isolate.reload();
+    // Use the isolate to communicate to the VM.
+  }
+];
+
+main(args) => runIsolateTestsSynchronous(args,
+                                        tests,
+                                        testeeConcurrent: code);
+```
+
+In order to test asynchronous operations:
+```dart
+import 'test_helper.dart';
+
+code() async{
+  // Write the asynchronous code you want to be execute into another VM.
+}
+
+var tests = [
+  // A series of tests that you want to run against the above code.
+  (Isolate isolate) async {
+    await isolate.reload();
+    // Use the isolate to communicate to the VM.
+  }
+];
+
+main(args) async => runIsolateTests(args,
+                                    tests,
+                                    testeeConcurrent: code);
+```
+
+Both ```runIsolateTests``` and ```runIsolateTestsSynchronous``` have the
+following named parameters:
+ - __testeeBefore__ (void()) a function that is going to be executed before
+the test
+ - __testeeConcurrent__ (void()) test that is going to be executed
+ - __pause_on_start__ (bool, default: false) pause the Isolate before the first
+instruction
+ - __pause_on_exit__ (bool, default: false) pause the Isolate after the last
+instruction
+ - __pause_on_unhandled_exceptions__ (bool, default: false) pause the Isolate at
+an unhandled exception
+ - __trace_service__ (bool, default: false) trace VM service requests
+ - __trace_compiler__ (bool, default: false) trace compiler operations
+ - __verbose_vm__ (bool, default: false) verbose logging
+
+
+Some common and reusable test are available from ```service_test_common.dart```:
+ - hasPausedFor
+   - hasStoppedAtBreakpoint
+   - hasStoppedWithUnhandledException
+   - hasStoppedAtExit
+   - hasPausedAtStart
+ - stoppedAtLine
+
+and utility functions:
+ - subscribeToStream
+ - cancelStreamSubscription
+ - asyncStepOver
+ - setBreakpointAtLine
+ - resumeIsolate
+ - resumeAndAwaitEvent
+ - resumeIsolateAndAwaitEvent
+ - stepOver
+ - getClassFromRootLib
+ - rootLibraryFieldValue
+
+## Run your tests
+See: __Run existing tests__
+
+[1]: https://github.com/dart-lang/sdk/wiki/Building "Building the Dart SDK"
+[2]: https://www.dartlang.org/tools/dartium/ "Download Dartium"
+[3]: https://github.com/dart-lang/sdk/wiki/Building-Dartium "Build Dartium"
+[4]: http://localhost:8080/ "Open Observatory"
+[5]: https://dart-lang.github.io/observatory/get-started.html "Observatory get started"
+[6]: https://github.com/dart-lang/sdk/wiki/Code-review-workflow-with-GitHub-and-reitveld "Code Review"
+[7]: https://pub.dartlang.org/packages/test "Test Library"