Contributing
Development setup
This page lists the tools you need to work on adocfmt and the commands that build, test and lint it.
Install the tools
- Go
Version 1.27 or later, as
go.modstates.- Asciidoctor
The release that the tests run with.
internal/corpuspins it, andtools/fetch-asciidoctor-casesprints it for you. Install it as a Ruby gem:gem install asciidoctor --version "$(go run ./tools/fetch-asciidoctor-cases --print-version)" --no-document- golangci-lint
Version 2, which reads the configuration in
.golangci.yml.- ShellCheck
Lints the shell scripts.
- lefthook
Runs the Git hooks defined in
lefthook.yml.- adocfmt
The latest release, which formats the documentation. Install adocfmt lists the ways to install it.
You do not install actionlint, which lints the GitHub workflows.
go tool builds it from the module in tools/actionlint, at the version pinned there.
Build
go build ./...Test
go test ./...The full run renders documents with Asciidoctor and loads it from Ruby, so Asciidoctor has to be on your PATH and ruby has to find the gem.
The gem install above sets up both.
To run only the tests that need no Asciidoctor, add -short:
go test -short ./...The testing strategy describes what the tests check.
Tip | With the Git hooks activated, every push runs go test ./… first. |
Lint
Lint the Go code:
golangci-lint runLint the shell scripts:
find . -name '*.sh' -not -path './.git/*' -exec shellcheck {} +Lint the GitHub workflows:
go tool -modfile=tools/actionlint/go.mod actionlintCheck the formatting of the documentation, leaving out the cases under testdata, which are meant to be unformatted:
adocfmt --check README.adoc CONTRIBUTING.adoc CODE_OF_CONDUCT.adoc docsTip | With the Git hooks activated, every commit runs these linters first. |
Build the website
The website is built from docs/ with Hugo, which go tool builds from the module in tools/hugo.
Build it and serve it at http://localhost:8080/adocfmt/:
go run ./tools/build-website --serveThe build downloads Pagefind, Mermaid and highlight.js in the versions that website/package-lock.json pins, so you do not need npm.
It fails when the front matter of a page does not match its title or lacks a field.
Check the links of the built website:
go tool -modfile=tools/htmltest/go.mod htmltest --conf website/htmltest.ymlActivate the Git hooks
Run this once in your clone:
lefthook install