Improve documentation for DDS and DTD

Change-Id: I51387b733af9e84509e28e1ba806a8be957232e9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/360903
Commit-Queue: Kenzie Davisson <kenzieschmoll@google.com>
Reviewed-by: Ben Konyi <bkonyi@google.com>

pkg/dds/CHANGELOG.md

@@ -2,6 +2,7 @@
 - Internal change: removed static method `DevToolsUtils.initializeAnalytics`
 and prepared DDS for using `unified_analytics` through the Dart Tooling Daemon.
 - Internal change: removed `analytics` parameter from the DevTools server `defaultHandler` method.
+- Updated `README.md` and added  contributing guide (`CONTRIBUTING.md`).
 
 # 4.0.0
 - Updated DDS protocol to version 2.0.

pkg/dds/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Development for `package:dds`
+
+One way to get stdout from files in DDS while debugging is to log messages to a file. You can add a method such as:
+
+```dart
+void _fileLog(String message) {
+  final file = File('/tmp/dds.log');
+  if (!file.existsSync()) {
+    file.createSync();
+  }
+  file.writeAsStringSync(
+'''
+$message
+''',
+    mode: FileMode.append,
+    flush: true,
+  );
+}
+```
+
+Then you can call `_fileLog('some print debugging message')`, and the log message will be written to a temp file.
+
+To get logging output in real time, run `tail -f /tmp/dds.log`.
+
+## Making changes to `package:dds` and `package:devtools_shared`
+
+**If you do not need to build the Dart SDK** to test your changes, you
+can add a `dependency_overrides` for `devtools_shared` that points to your
+local `devtools_shared` directory from path:
+
+```yaml
+dependency_overrides:
+  devtools_shared:
+    path: ../../relative_path_to/devtools/packages/devtools_shared
+```
+
+**If you do need to build the Dart SDK** to test your changes, in addition
+to adding the dependency override above, you will need to add a symbolic link
+to your local `devtools_shared` directory:
+
+From the `sdk/` directory, run:
+```shell
+rm -rf third_party/devtools/devtools_shared;
+ln -s /absolute_path_to/devtools/packages/devtools_shared third_party/devtools/devtools_shared
+```
+
+**WARNING**: do not run `gclient sync -D` while the symbolic link is present,
+as this could cause issues with your local `devtools_shared` code.
+
+To delete the symbolic link after you are done with development, run:
+```shell
+rm -rf third_party/devtools/devtools_shared
+```

pkg/dds/README.md

@@ -37,26 +37,3 @@ void main() {
 
 [dds-protocol]: dds_protocol.md
 [service-protocol]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md
-
-# Debugging DDS
-
-One way to get stdout from files in DDS while debugging is to log messages to a file. You can add a method such as:
-
-```dart
-void _fileLog(String message) {
-  final file = File('/tmp/dds.log');
-  if (!file.existsSync()) {
-    file.createSync();
-  }
-  file.writeAsStringSync(
-'''
-$message
-''',
-    mode: FileMode.append,
-  );
-}
-```
-
-Then you can call `_fileLog('some print debugging message')`, and the log message will be written to a temp file.
-
-To get logging output in real time, run `tail -f /tmp/dds.log`.

pkg/dtd/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 2.2.0
 - Added new response types `Success`, `StringResponse`, `BoolResponse`, and `StringListResponse`.
+- Added  contributing guide (`CONTRIBUTING.md`).
 
 ## 2.1.0
 - Added `getProjectRoots` API.

pkg/dtd/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing guide
+
+When making changes to `package:dtd` and `package:dtd_impl` at the same
+time, you'll need to
+[build the Dart SDK](https://github.com/dart-lang/sdk/wiki/Building#building)
+to ensure that changes to
+`package:dtd_impl` are picked up in the DTD snapshot.
+
+## Helpful aliases
+
+Consider adding these aliases to your `.zshrc` file for convenience. For
+non-macOS platforms, replace "xcodebuild" with "out".
+```
+# Builds the entire Dart SDK. Run from the sdk/ directory.
+alias build-dart='./tools/build.py -mrelease create_sdk'
+
+# The create_platform_sdk target will work exactly the same as the
+# `create_sdk` target but without building the web tooling.
+alias build-dart-fast='./tools/build.py -mrelease create_platform_sdk'
+
+# The dart exe that was built by running 'build-dart' or 'build-dart-fast'
+# will be located here. Create an alias for convenience of using the dart exe.
+alias sdkdart='/absolute_path_to/sdk/xcodebuild/ReleaseX64/dart-sdk/bin/dart'
+
+# The runtime target will only build what the VM needs to run, but will output
+# the compiled dart binary at `xcodebuild/ReleaseX64/dart` instead of
+# `xcodebuild/ReleaseX64/dart-sdk/bin/dart`. Runtime is a bit faster than
+# `create_platform_sdk`, but both are faster than `create_sdk`.
+alias build-dart-runtime='./tools/build.py -mrelease runtime'
+
+# The dart exe that was built by running `build-dart-runtime`.
+alias sdkruntime='/absolute_path_to/sdk/xcodebuild/ReleaseX64/dart'
+```
+
+After building the Dart SDK with your local changes, use the `dart`
+executable that you just built to run commands that you want your
+local changes applied to (e.g. `sdkdart run ...`, `sdkdart test ...`).