Skip to content

Commit

Permalink
development docs (#26)
Browse files Browse the repository at this point in the history
  • Loading branch information
@samsalisbury
samsalisbury committed Jan 11, 2023
1 parent 941a719 commit 75a9f70
Show file tree
Hide file tree
Showing 3 changed files with 126 additions and 78 deletions.
90 changes: 13 additions & 77 deletions README.md
View file
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
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.
3 changes: 2 additions & 1 deletion dev/git_hooks/pre-push
View file
Expand Up @@ -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.
Expand Down
111 changes: 111 additions & 0 deletions docs/development.md
View file
@@ -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 <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) 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:

```
<!-- insert:path/to/executable -->
...
... Some content here.
...
<!-- end:insert:path/to/executable -->
```

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<VERSION>.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.

0 comments on commit 75a9f70

Please sign in to comment.