Skip to content

Latest commit

 

History

History
169 lines (113 loc) · 5.19 KB

CONTRIBUTING.md

File metadata and controls

169 lines (113 loc) · 5.19 KB

Development

make (3.81 or later) is useful to run each tasks and reduce redundant builds/tests.

How to build

go build ./cmd/actionlint
./actionlint -h

or

make build

It generates some sources with go generate.

How to run tests

go test

or

make test

How to run lint

staticcheck is used to lint Go sources.

staticcheck ./ ./cmd/...

or

make lint

Note that staticcheck ./... is not available because it does not support syscall/js yet. playground/main.go hits this issue.

How to run fuzzer

Fuzz tests use go-fuzz. Install go-fuzz and go-fuzz-build in your system.

Since there are multiple fuzzing targets, -func argument is necessary. Specify a target which you want to run.

# Create first corpus
go-fuzz-build ./fuzz

# Run fuzzer
go-fuzz -bin ./actionlint_fuzz-fuzz.zip -func FuzzParse

or

make fuzz FUZZ_FUNC=FuzzParse

How to release

When releasing v1.2.3 as example:

  1. Ensure all changes were already pushed to remote by checking git push origin master outputs Everything up-to-date
  2. git tag v1.2.3 && git push origin v1.2.3
  3. Wait until the CI release job completes successfully:
    • GoReleaser builds release binaries and make pre-release at GitHub and updates Homebrew formula
    • The CI job also updates version string in ./scripts/download-actionlint.bash
  4. Open the pre-release at release page with browser
  5. Write up release notes, uncheck pre-release checkbox and publish the new release
  6. Run git pull && changelog-from-release > CHANGELOG.md locally to update CHANGELOG.md

How to generate manual

actionlint.1 manual is generated from actionlint.1.ronn by ronn.

ronn ./man/actionlint.1.ronn

or

make ./man/actionlint.1

How to develop playground

Visit playground/README.md.

How to deploy playground

Run deploy.bash at root of repository. It does:

  1. Ensures to install dependencies and to build main.wasm
  2. Copy all assets to ./playground-dist directory
  3. Optimize main.wasm with wasm-opt which is a part of Binaryen toolchain
  4. Switch branch to gh-pages
  5. Move all files in ./playground-dist to root of repository and add to repository
  6. Make commit for deployment
# Prepare deployment
bash ./playground/deploy.bash
# Check it works fine by visiting localhost:1234
npm run serve
# If it looks good, deploy it
git push

Inspect workflow AST

Please use actionlint-workflow-ast script.

go run ./scripts/actionlint-workflow-ast /path/to/workflow.yaml

Maintain popular_actions.go

popular_actions.go is generated automatically with go generate. The command runs generate-popular-actions script.

The script also can detect new releases of popular actions on GitHub by giving -d flag.

Detecting new release and updating popular_actions.go are run weekly on CI by generate workflow. Runs can be checked here.

Maintain all_webhooks.go

[all_webhooks.go(./all_webhooks.go) is a table all webhooks supported by GitHub Actions to trigger workflows. Note that not all webhooks are supported by GitHub Actions.

It is generated automatically with go generate. The command runs generate-webhook-events script.

It fetches events-that-trigger-workflows.md, parses the markdown document, and extracts webhook names and their types. For more details, see README.md at the script.

Updating all_webhooks.go is run weekly on CI by generate workflow.

Maintain actionlint-matcher.json

actionlint-matcher.json is a matcher configuration to extract error annotations from outputs of actionlint command. See the document for its usage.

The regular expression is complicated because it can matches to outputs which contain ANSI color escape sequences. So the JSON file is not modified manually.

It is generated by generate-actionlint-matcher script. See the README.md file for the usage of the script and how to run the tests for it.

Testing

  • All examples in 'Checks' section are put in the examples directory and tested in linter_test.go.
  • I cloned GitHub top 1000 repositories and extracted 1400+ workflow files. And I tried actionlint with the collected workflow files. All bugs found while the trial were fixed and I confirmed no more false positives.