Development

Working on go-asyncapi itself. You need Docker and Make, nothing else. Every Go and tooling command runs inside the image built from Dockerfile.dev, so the Go toolchain (1.26.10), golangci-lint and the security scanners are the same in a local shell and in CI. The image runs as your user with every capability dropped, and the checkout is mounted at /work.

Layout

Path	Holds
document.go	Load, the section loaders and the exported document types.
resolver.go	Resolver and Location: file loading, the cache, $ref chains and JSON pointers.
node.go	Object and the conversion of yaml.v3 nodes into Go values.
traits.go	Message and operation trait merging.
testdata/	Specs the tests load. kitchensink.yaml and external.yaml use every AsyncAPI 3.0 object; the rest are small cases, some deliberately broken.
scripts/	The lint, coverage and security scan scripts the Makefile runs.
vendor/	Committed dependencies, regenerated by make dep.
docs/	This site.
.agents/	The agent skill, its plugin manifests, and the contributor rules.

Make targets

Run make help for the list. The Makefile has:

Target	What it does
make dev-image	Builds the dev image. Every target below that runs Go builds it first.
make all	Runs dep, lint and test, in that order.
make dep	go mod tidy and go mod vendor.
make format	gofmt -w on the Go source and shfmt -w on scripts/.
make lint	shellcheck and shfmt -d on scripts/, fails if go fix -diff ./... has suggestions, then runs golangci-lint with the rules in .golangci.yml.
make lint-fix	Applies go fix ./... and runs golangci-lint with --fix.
make test	go test -race -count=1 ./.... make test-unit is the same.
make test-coverage	The tests with -race and a coverage profile. Writes the total to coverage-percent.txt and fails below 90 percent.
make sec	gitleaks over the working tree and the Git history, govulncheck, and semgrep with the p/golang and p/security-audit rule sets. Writes one merged sec.sarif and fails on any finding.
make docs	Builds this site locally with the image GitHub Pages uses.
make shell	Opens a shell in the dev image.

golangci-lint comes from the module’s own tool dependency in go.mod and is vendored, so go tool golangci-lint needs no install. Lines are limited to 80 columns.

Tests

The tests are black-box, in package asyncapi_test, and use only the exported API. The happy paths load testdata/kitchensink.yaml. Error branches are rows in TestLoadRejectsMalformedSections in malformed_test.go, which writes small temp specs with writeDocument.

Docs site

The site is Just the Docs, built by GitHub Pages straight from docs/ on main. make docs runs the same build image locally and writes the result to a gitignored directory. Links between pages are relative .md paths. Links to files outside docs/ use the full GitHub URL, because a relative path out of docs/ does not exist on the site.

CI

.github/workflows/pipeline.yml calls the shared workflows in psyb0t/reusable-github-workflows:

Job	Runs on	Does
code	every branch push	make lint, make test-coverage and make sec through code-workflow.yml, uploads the coverage file and the SARIF report. No credentials.
badges	main, tags	Republishes the coverage, version, license and imported-by badges to the badges branch.
wait	tags	Waits for the main run of the tagged commit to succeed. A tag does not rerun the checks.
release	tags, after wait	Cuts the GitHub release from the annotated tag message.
publish-to-clawhub	every branch push, tags	Validates the agent skill after code. On a tag it also publishes the skill to ClawHub after release.

A weekly scheduled run keeps the imported-by badge current.

Releases

The git tag is the version. Each release prepends a ## vX.Y.Z, YYYY-MM-DD section to CHANGELOG.md, moves the version in the Codex plugin manifest, and tags the commit with an annotated tag whose message is that section. Before 1.0, a breaking change to the exported API bumps the minor version.