tast: Add modifying_tast.md and update Go links.
Add a new "Modifying Tast" document that explains how to
make and test changes to the framework itself.
Also add a few more links to helpful Go documentation
sources and make writing_tests.md link to the new document's
explanation of fast_build.sh.
BUG=none
TEST=viewed using md_browser
Change-Id: I48aa816555d5840071fc2c5ae71f68800d5e8ce6
Reviewed-on: https://chromium-review.googlesource.com/c/1292617
Reviewed-by: Dan Erat <derat@chromium.org>
Tested-by: Dan Erat <derat@chromium.org>
diff --git a/docs/modifying_tast.md b/docs/modifying_tast.md
new file mode 100644
index 0000000..506b37b
--- /dev/null
+++ b/docs/modifying_tast.md
@@ -0,0 +1,93 @@
+# Modifying Tast
+
+This document describes how to make changes to the Tast framework itself. For
+information about writing Tast tests, see [Writing Tests].
+
+[Writing Tests]: writing_tests.md
+
+[TOC]
+
+## Components
+
+See the [Overview] document for a high-level description of the key components
+and terminology in Tast.
+
+[Overview]: overview.md
+
+### Executables
+
+* The [tast executable] is run by developers and by builders. It's used to
+ compile, deploy, and run tests and to collect results.
+* [local_test_runner] is run on the DUT by the `tast` process over an SSH
+ connection. It collects system information and initiates running local
+ tests.
+* [remote_test_runner] is run on the host system by the `tast` process to
+ initiate running remote tests.
+
+### Libraries
+
+Shared library packages are located under the [tast directory]. Several packages
+are particularly important:
+
+* [bundle] contains code used to implement test bundles, which contain
+ compiled tests and are executed by test runners.
+* [control] defines control messages that are used for communication between
+ the `tast` process, test runners, and test bundles.
+* [host] opens SSH connections.
+* [runner] contains code shared between `local_test_runner` and
+ `remote_test_runner`.
+* [testing] contains code used to define and run tests.
+
+[tast executable]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/cmd/tast/
+[local_test_runner]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/cmd/local_test_runner/
+[remote_test_runner]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/cmd/remote_test_runner/
+[tast directory]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/tast/
+[bundle]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/tast/bundle/
+[control]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/tast/control/
+[host]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/tast/host/
+[runner]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/tast/runner/
+[testing]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/src/chromiumos/tast/testing/
+
+## Compiling changes
+
+### fast_build.sh
+
+The quickest way to rebuild the `tast` executable after modifying its code is by
+running the [fast_build.sh] script located at the top of the `src/platform/tast`
+repository within the Chrome OS chroot. This script bypasses Portage and runs
+`go build` directly, allowing it to take advantage of [Go's build cache]. Since
+dependency checks are skipped, there's no guarantee that the resulting
+executable is correct – before uploading a change, you should verify it that it
+builds when you run `FEATURES=test sudo emerge tast-cmd` (after running
+`cros_workon --host start tast-cmd`).
+
+* Without any arguments, `fast_build.sh` compiles the `tast` executable to
+ `$HOME/bin/tast`.
+* `fast_build.sh -t chromiumos/tast/testing` runs the unit tests for the
+ `chromiumos/tast/testing` package.
+* `fast_build.sh -T` runs all unit tests (including ones in the `tast-tests`
+ repository).
+* `fast_build.sh -c chromiumos/tast/testing` runs `go vet` against the
+ `chromiumos/tast/testing` package.
+* `fast_build.sh -C` vets all packages.
+
+Run `fast_build.sh -h` to see all available options.
+
+[fast_build.sh]: https://chromium.googlesource.com/chromiumos/platform/tast/+/master/fast_build.sh
+[Go's build cache]: https://golang.org/cmd/go/#hdr-Build_and_test_caching
+
+## Testing changes
+
+### Unit tests
+
+The different components of the framework are extensively covered by unit tests.
+Please ensure that any changes that you make are also covered by tests.
+
+### Meta tests
+
+There are several [meta tests]. These are remote Tast tests that run a nested
+instance of the `tast` executable to perform end-to-end verification of
+interactions between `tast`, test runners, and test bundles. They're executed
+the same way as other Tast tests, i.e. via `tast run`.
+
+[meta tests]: https://chromium.googlesource.com/chromiumos/platform/tast-tests/+/HEAD/src/chromiumos/tast/remote/bundles/cros/meta/
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 0b89c77..93eed04 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -103,6 +103,8 @@
* [A Tour of Go] - In-browser introduction to Go's core features.
* [Official Go documentation] - Package documentation, specifications, blog
posts, and recorded talks.
+* [Go at Google: Language Design in the Service of Software Engineering] -
+ High-level overview of Go's features and design philosophy.
* [Community Learn wiki] - Links to external resources.
[Chrome OS chroot]: http://www.chromium.org/chromium-os/quick-start-guide
@@ -114,4 +116,5 @@
[tast repository]: https://chromium.googlesource.com/chromiumos/platform/tast/
[A Tour of Go]: https://tour.golang.org/
[Official Go documentation]: https://golang.org/doc/
+[Go at Google: Language Design in the Service of Software Engineering]: https://talks.golang.org/2012/splash.article
[Community Learn wiki]: https://github.com/golang/go/wiki/Learn
diff --git a/docs/writing_tests.md b/docs/writing_tests.md
index 5cfeee8..1f2db26 100644
--- a/docs/writing_tests.md
+++ b/docs/writing_tests.md
@@ -101,23 +101,48 @@
* [Effective Go]
* [Go Code Review Comments]
+The [Go FAQ] may also be helpful. Additional resources are linked from the [Go
+Documentation] page.
+
[gofmt]: https://golang.org/cmd/gofmt/
[go vet]: https://golang.org/cmd/vet/
[Effective Go]: https://golang.org/doc/effective_go.html
[Go Code Review Comments]: https://github.com/golang/go/wiki/CodeReviewComments
+[Go FAQ]: https://golang.org/doc/faq
+[Go Documentation]: https://golang.org/doc/
+
+### Documentation
+
+Packages and exported identifiers (e.g. types, functions, constants, variables)
+should be documented by [Godoc]-style comments. Godoc comments are optional for
+test functions, since the `Test.Desc` field already contains a brief description
+of the test.
+
+[Godoc]: https://blog.golang.org/godoc-documenting-go-code
### Unit tests
Support packages should be exercised by unit tests when possible. Unit tests can
cover edge cases that may not be typically seen when using the package, and they
greatly aid in future refactorings (since it can be hard to determine the full
-set of Tast-based tests that must be run to exercise the package). See [Go's
-testing package] for more information about writing unit tests for Go code. The
-[Best practices for writing Chrome OS unit tests] document contains additional
-suggestions that may be helpful (despite being C++-centric).
+set of Tast-based tests that must be run to exercise the package). See [How to
+Write Go Code: Testing] and [Go's testing package] for more information about
+writing unit tests for Go code. The [Best practices for writing Chrome OS unit
+tests] document contains additional suggestions that may be helpful (despite
+being C++-centric).
+Setting `FEATURES=test` when emerging a test bundle package
+(`tast-local-tests-cros` or `tast-remote-tests-cros`) will run all unit tests
+for the corresponding packages in the `tast-tests` repository (i.e.
+`chromiumos/tast/local/...` or `chromiumos/tast/remote/...`, respectively).
+
+During development, the [fast_build.sh] script can be used to quickly build and
+run tests for a single package or all packages.
+
+[How to Write Go Code: Testing]: https://golang.org/doc/code.html#Testing
[Go's testing package]: https://golang.org/pkg/testing/
[Best practices for writing Chrome OS unit tests]: https://chromium.googlesource.com/chromiumos/docs/+/master/unit_tests.md
+[fast_build.sh]: modifying_tast.md#fast_build_sh
### Import
@@ -320,7 +345,14 @@
* `Fatal` and `Fatalf` record errors and stop the test immediately, similar to
the `ASSERT_` set of macros.
+Note that higher-level functions for stating expectations and assertions are not
+provided; this was a conscious decision. See ["Where is my favorite helper
+function for testing?"] from the [Go FAQ]. That answer refers to [Go's testing
+package] rather than Tast's, but the same reasoning and suggestions are
+applicable to Tast tests.
+
[Google Test]: https://github.com/google/googletest
+["Where is my favorite helper function for testing?"]: https://golang.org/doc/faq#testing_framework
### When to log
