development docs

README.md

@@ -10,16 +10,13 @@ _This is intended for internal HashiCorp use only; Internal folks please refer t
 
 <!-- insert:dev/docs/table_of_contents -->
 * [Features](#features)
-* [Usage](#usage)
+* [Local Usage](#local-usage)
+* [Usage in GHA](#usage-in-gha)
   * [Examples](#examples)
   * [Inputs](#inputs)
   * [Build Instructions](#build-instructions)
   * [Ensuring Reproducibility](#ensuring-reproducibility)
 * [Development](#development)
-  * [Tests](#tests)
-  * [Documentation](#documentation)
-  * [Releasing](#releasing)
-  * [Implementation](#implementation)
 <!-- end:insert:dev/docs/table_of_contents -->
 
 ## Features
@@ -30,12 +27,15 @@ _This is intended for internal HashiCorp use only; Internal folks please refer t
 - **Reproducibility** is checked at build time.
 - **Fast feedback** if accidental nondeterminism is introduced.
 
-## Usage
+## Local Usage
 
-This Action can run on both Ubuntu and macOS runners.
+The core functionality of this action is contained in a Go CLI, which
+you can also install and use locally. See [the CLI docs](docs/cli.md)
+for more.
+
+## Usage in GHA
 
-The core functionality is contained in a Go CLI, which you can also install and
-use locally. See [the CLI docs](docs/cli.md) for local usage.
+This Action can run on both Ubuntu and macOS runners.
 
 ### Examples
 
@@ -270,72 +270,8 @@ turn this off using the `-buildvcs=false` flag.
 
 ## Development
 
-- This Action uses extensionless executable bash scripts in `scripts/` to perform each step.
-- There are also `.bash` files in `scripts/` which define functions used in the executables.
-- Both executable and library bash files have BATS tests which are defined inside files with
-  the same name plus a `.bats` extension.
-
-### Tests
-
-**All code changes in this Action should be accompanied by new or updated tests documenting and
-preserving the new behaviour.**
-
-Run `make test` to run the BATS tests which cover the scripts.
-
-There are also tests that exercise the action itself, see
-[`.github/workflows/test.yml`](https://github.com/hashicorp/actions-go-build/blob/main/.github/workflows/test.yml).
-These tests use a reusable workflow for brevity, and assert both passing and failing conditions.
-
-The example code is also tested to ensure it really works, see
-[`.github/workflows/example.yml`](https://github.com/hashicorp/actions-go-build/blob/main/.github/workflows/example.yml)
-and
-[`.github/workflows/example-matrix.yml`](https://github.com/hashicorp/actions-go-build/blob/main/.github/workflows/example-matrix.yml).
-
-### Documentation
-
-Wherever possible, the documentation in this README is generated from source code to ensure
-that it is accurate and up-to-date. Run `make docs` to update it.
-
-#### Changelog
-
-All changes should be accompanied by a corresponding changelog entry.
-Each version has a file named `dev/changes/v<VERSION>.md` which contains
-the changes added during development of that version.
-
-### Releasing
-
-You can release a new version by running `make release`.
-This uses the version string from `dev/VERSION` to add tags,
-get the corresponding changelog entries, and create a new GitHub
-release.
-
-### Implementation
-
-#### Bash, dreaded bash.
-
-This Action is currently written in Bash.
-
-The primary reason is that Bash makes it trivial to call other programs and handle the
-results of those calls. Relying on well-known battle-tested external programs like
-`sha256sum` and `bash` itself (for executing the instructions) seems like a reasonable
-first step for this Action, because they are the tools we'd use to perform this work
-manually.
-
-For the initial development phase, well-tested Bash is also useful because of the speed
-and ease of deployment. It is present on all runners and doesn't require a compilation
-and deployment step (or alternatively installing the toolchain to perform that
-compilation).
-
-#### Future Implementation Options
-
-Once we're happy with the basic shape of this Action, there will be options to implement
-it in other ways. For example as a composite action calling Go programs to do all the work,
-or calling Go programs to do the coordination of calling external programs,
-or as a precompiled Docker image Action
-(though that would present problems for Darwin builds which rely on macOS and CGO).
-
-#### TODO
+Devlopment docs have moved to [docs/development.md](docs/deveopment.md).
 
-- Add a reusable workflow for better optimisation (i.e. running in parallel jobs)
-- Store build metadata for external systems to use to reproduce the build.
-- See **ENGSRV-083** (internal only) for future plans.
+The core functionality of this action is contained in a Go CLI, which can also be installed
+and run locally. See [the CLI docs](docs/cli.md) for instructions on installing and using
+the CLI.

docs/development.md

@@ -0,0 +1,66 @@
+# Development
+
+This action's core functionality is contained in a Go CLI. The `action.yml` at the root of
+this repo defines the action itself, as a composite action, that builds and then calls the CLI.
+
+## Manually Testing the CLI
+
+It's useful to be able to just run the CLI locally to manually poke around and see your changes.
+
+The workflow for this is to run `make install` any time you want to test your local changes,
+this runs tests and does a fully dogfooded from-scratch build and installs it into your PATH.
+
+You can then run `actions-go-build <blah>` to test things out.
+
+## Tests
+
+**All code changes in this Action should be accompanied by new or updated tests documenting and
+preserving the new behaviour.**
+
+### CLI Tests
+
+Run `make test` to run the CLI tests locally. These tests are run in CI by the
+`test.yml` workflow.
+
+### End-to-End Action Tests
+
+There are tests that exercise the action itself, see
+[`test-build.yml`](.github/workflows/test-build.yml).
+
+That test file invokes the entire test suite `self-test-suite.yml` twice, once on Linux
+runners and again on macOS runners. They are the two runner OSs supported by this action.
+
+The `self-test-suite.yml` calls the test harness action (see below) mutliple times to
+simulate different conditions and assert on the results.
+
+There is a special action defined in `self-test/action.yml` which is a test harness for
+the main action. It has all the same inputs as the action itself, and passes these through
+but sets some alternative default input values that make testing easier, and provides built-in
+assertions. This keeps the test suite nice an concise.
+
+### Example Code
+
+The example code in the readme is real, working code that we run on every push.
+This ensures that it doesn't go out of date.
+
+[`.github/workflows/example.yml`](.github/workflows/example.yml)
+and
+[`.github/workflows/example-matrix.yml`](.github/workflows/example-matrix.yml).
+
+## Documentation
+
+Wherever possible, the documentation in this README is generated from source code to ensure
+that it is accurate and up-to-date. Run `make docs` to update it.
+
+### Changelog
+
+All changes should be accompanied by a corresponding changelog entry.
+Each version has a file named `dev/changes/v<VERSION>.md` which contains
+the changes added during development of that version.
+
+## Releasing
+
+You can release a new version by running `make release`.
+This uses the version string from `dev/VERSION` to add tags,
+get the corresponding changelog entries, and create a new GitHub
+release.