diff --git a/README.md b/README.md index 74e93942..d17e4478 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,13 @@ _This is intended for internal HashiCorp use only; Internal folks please refer t * [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) ## 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.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 +Development docs have moved to [docs/development.md](docs/development.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. diff --git a/dev/git_hooks/pre-push b/dev/git_hooks/pre-push index 665896f8..2ec9835e 100755 --- a/dev/git_hooks/pre-push +++ b/dev/git_hooks/pre-push @@ -116,7 +116,8 @@ do assert_success "$local_oid" "Compilation" go build ./... # Check for version consistency. - assert_success "$local_oid" "Version check" make version/check + # Disabled for now, this might be overkill. + #assert_success "$local_oid" "Version check" make version/check # Check for changelog update, only if the push includes both a # test change and a non-test change to the Go code. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..7d918eb7 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,111 @@ +# 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. + +## Git Push Hooks + +In order to prevent accidentally pushing broken code, this repo installs a git pre-push hook +`dev/git_hooks/pre-push` by copying it to `.git/hooks/`. +The hook checks that compilation and tests are successful, and that documentation is up-to-date. + +Sometimes these hooks + +## 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 override the destination by setting `DESTDIR` e.g. `make install DESTDIR=/some/path` + +You can then run `actions-go-build ` 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) multiple 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 and 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. Some of the examples are also directly included +in the readme. + +[`.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. + +The `make docs` target updates both the readme and the changelog +(`make readme` and `make changelog`). + +### Readme + +The Readme contains blocks like this: + +``` + +... +... Some content here. +... + +``` + +These blocks are auto-updated when we run `make readme` or `make docs`. +They are updated by the script at `dev/docs/readme_update` which calls +`dev/docs/insert` to replace the contents of those blocks with the output +from the named executable. + +For example, the executable at `dev/docs/print_example_workflow` gets the contents +of an example workflow, and formats it as markdown. + +Another more complex example is `dev/docs/environment_doc` which uses the `run` +script at the root of this repo to build the CLI, then execute it to get the +output of `inspect -describe-build-env` and format it as a markdown table. + +Doing all these things by hand would be error-prone, and easy to forget. +With these automations the source code and documentation are guaranteed to +be congruent. + +### Changelog + +All changes should be accompanied by a corresponding changelog entry. +Each version has a file named `dev/changes/v.md` which contains +the changes added during development of that version. + +When a release is made (see below) the contents of the changelog file are +copied into the release description. + +## 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.