x/exp/cmd/gorelease: add more documentation for version
Version and release are a bit confusing: naively, they seem like the same thing.
Version also doesn't have a lot of documentation around it.
I tend to forget what version is used for, and have many times spent time
re-remembering. So, I figured I'd write it down for future developers.
Change-Id: Ic649d5625032bf2cb2f98a294f9689ef2d8e1d5e
Reviewed-on: https://go-review.googlesource.com/c/exp/+/304149
Trust: Jean de Klerk <deklerk@google.com>
Run-TryBot: Jean de Klerk <deklerk@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>
diff --git a/cmd/gorelease/testdata/README.md b/cmd/gorelease/testdata/README.md
index 9be53a3..9a3a234 100644
--- a/cmd/gorelease/testdata/README.md
+++ b/cmd/gorelease/testdata/README.md
@@ -34,7 +34,7 @@
the content of a module out of the test proxy into a temporary directory
where `gorelease` is run.
* `version`: specified together with `mod`, it sets the version to retrieve from
- the test proxy.
+ the test proxy. See more information below.
* `base`: the value of the `-base` flag passed to `gorelease`.
* `release`: the value of the `-version` flag passed to `gorelease`.
* `dir`: the directory where `gorelease` should be invoked. Useful when the test
@@ -52,6 +52,30 @@
If the `mod` and `version` parameters are not set, other files will be extracted
to the temporary directory where `gorelease` runs.
+## Populating module contents
+
+When building a test in `testdata/`, there are two ways to populate the module
+directory being tested:
+
+### Option 1: inline
+
+You can inline files in the `.test` folder as described in
+https://pkg.go.dev/golang.org/x/tools/txtar#hdr-Txtar_format. For example,
+
+```
+-- some.file --
+the contents
+of the file
+```
+
+### Option 2: specify an existing file
+
+Often, multiple tests want to share the same setup - the same files. So, users
+can write these common files in `testdata/mod/`, and use one of these files as
+the module directory contents.
+
+To specify a file in `testdata/mod/` to use as the module contents.
+
## Module format
Tests run with `GOPROXY` set to a local URL that points to a test proxy. The
