Table of contents
Working on nurago itself, or on a project generated from it.
Clone and Validate
git clone https://github.com/tecnickcom/nurago.git
cd nurago
make x
make x runs the whole flow from scratch: update the library version in the examples, format, clean, download and get dependencies, generate code, regenerate the documentation, run the QA pipeline, then build and test the service example. All artifacts and reports land in target/.
Requirements: Go 1.26.0 or later. No CGO.
Make Targets
make help lists everything. The ones used most often:
| Target | What it does |
|---|---|
make x | Test and build everything from scratch |
make qa | Linters, vulnerability check, unit tests, coverage |
make test | Unit tests, with -shuffle=on, -race, atomic coverage, and benchmarks run once |
make linter | golangci-lint over the whole tree, no per-linter issue cap |
make govulncheck | Check dependencies for known vulnerabilities |
make coverage | Coverage report (target/report/coverage.html) |
make format | Format the source |
make generate | Regenerate the test mocks |
make gendoc | Regenerate the package READMEs and llms.txt from the source |
make gendoccheck | Fail when the generated documentation is out of date |
make modcheck | Fail when go.mod and go.sum are not tidy |
make example | Build and test the service example |
make project CONFIG=... | Generate a new project (/docs/service-scaffolding/) |
make dbuild | Run the whole build inside a Docker container |
Maintenance targets: make updatego, make updatemod, make updatelint, make updateall, make versionup, make tag.
Docker
make dbuild
builds a development image from resources/docker/Dockerfile.dev and runs the build inside it, so the toolchain versions are pinned regardless of what is installed locally. dockerbuild.sh is the underlying script and takes CVSPATH, VENDOR, PROJECT, and MAKETARGET from the environment.
Benchmarks and Allocation Gates
make bench # results into target/report/bench.txt
make benchbase # baseline into target/report/bench_base.txt
make benchcmp BENCHBASE=main # compare against a git ref, fail on regression
make benchgate BASELINE=path # compare against a stored baseline file
Benchmarks run without -race and without coverage so the numbers mean something. The comparison targets fail the build on an allocation-count regression, which is how the hot paths (redaction, hex encoding, trie lookup) hold their performance across releases.
Generated Documentation
The per-package README.md files and the repository llms.txt are generated from the package source documentation by resources/gendoc/gendoc.sh. They carry a “do not edit” header for that reason: change the package documentation comment in the .go file and run make gendoc. make gendoccheck runs in CI, so a documentation change that was not regenerated fails the build.
The package pages on this website are generated from those same READMEs.
Feedback and Contributions
The terms are on the home page: issues welcome, code contributions limited to project collaborators, CONTRIBUTING.md and CODE_OF_CONDUCT.md for the details, and SECURITY.md rather than a public issue for vulnerabilities.
What this page adds is the standards every accepted change is held to:
- Follow the existing conventions in the package being changed.
- A bug fix comes with a test covering the specific case.
- Unit test coverage is maintained at 100%.
- A new feature comes with package documentation, examples, and benchmarks where appropriate.
make xpasses locally.
Because the exported API of every pkg/ package is stable within v1, a change to an exported symbol’s signature or behaviour is not a patch: it needs a different design, or a v2 module path. Additive changes are the usual route.
Previous: /docs/migration-from-gogen/
Overview: /docs/
Next: /docs/ai-assistants/