ynh Development Workflow
You are helping a developer work on the ynh codebase.
References
Read these before starting work:
references/architecture.md - Package structure, core flow, adapter interface, design decisionsreferences/coding-standards.md - Go coding standards: package design, interfaces, errors, testing, CLI patternsreferences/building.md - Build system, Makefile targets, and tool path conventionsreferences/skill-authoring.md - Required reading (https://agentskills.io/) before creating or modifying skillsreferences/agent-and-baseline.md - The agent loop and the baseline ratchet: convergence, stuckness, budgets, checkpoints, trajectory redaction, and why the gate forgives what it does
Quick checks
Run the full CI pipeline:
make check
This runs deps, format, lint, test, and build in sequence. Fix any issues before committing.
Individual steps
If you need to run steps individually:
make deps # install prerequisites (goimports, golangci-lint)
make format # goimports + gofmt
make lint # golangci-lint
make test # go test with race detection and coverage
make build # build binary to bin/ynh
Target a specific package:
make test FILE=./cmd/ynh
make test FILE=./internal/assembler
Before committing
- Run
make check - all steps must pass
- Check test coverage - new features should include tests
- Review the test matrix in
references/architecture.md if touching assembler/resolver logic
Manual testing
After code changes, verify against the relevant tutorial in docs/tutorial/.
docs/tutorial/manual-test-plan.md adds edge cases the tutorials do not cover.
Tutorial filenames are descriptive, not numbered — do not cite them by number.
| Package / area |
Tutorial |
cmd/ynh (install, run, ls, uninstall) |
first-harness.md |
internal/vendor, internal/symlink |
vendors-and-symlinks.md |
internal/resolver (includes, Git sources) |
composition.md |
internal/assembler (delegates) |
delegation.md |
internal/exporter |
export.md |
internal/marketplace |
marketplace.md |
internal/registry, internal/sources |
registry-and-discovery.md |
cmd/ynd (create, lint, validate, fmt, compress) |
developer-tools.md |
cmd/ynd (preview, compose, diff) |
developer-preview.md |
| Docker image build |
docker-image.md |
| Hooks |
hooks.md |
| MCP servers |
mcp-servers.md |
| Profiles |
profiles.md |
| Focus |
focus.md |
| Project-local config |
project-local-config.md |
internal/clischema, internal/jsonschema |
structured-output.md |
ynh include editing |
include-editing.md |
internal/namespace, internal/migration |
namespacing-and-migration.md |
internal/plugin (sensor declarations) |
sensors.md |
internal/gate, internal/baseline |
check.md |
internal/agent |
agent-loop.md |
internal/freshness, shadow mode |
shadow-mode.md |
Run the relevant tutorial steps end-to-end before committing. Build first with
make build so the binaries reflect your changes. The tutorials use /tmp/ as
a scratch directory; the evals agent has the isolation rules.
Common issues
- Tool not found: The Makefile uses full paths to GOPATH/bin for go-installed tools. Run
make deps if tools are missing.
- Lint errors:
errcheck is strict - all returned errors must be handled, even in tests
- Test isolation: Always use
t.TempDir() and t.Setenv("YNH_HOME", "") to avoid leaking state
1---2name: ynh-dev3description: Development workflow for the ynh codebase. Build, test, lint, and format in the right order.4---56# ynh Development Workflow78You are helping a developer work on the ynh codebase.910## References1112Read these before starting work:1314- `references/architecture.md` - Package structure, core flow, adapter interface, design decisions15- `references/coding-standards.md` - Go coding standards: package design, interfaces, errors, testing, CLI patterns16- `references/building.md` - Build system, Makefile targets, and tool path conventions17- `references/skill-authoring.md` - Required reading (https://agentskills.io/) before creating or modifying skills18- `references/agent-and-baseline.md` - The agent loop and the baseline ratchet: convergence, stuckness, budgets, checkpoints, trajectory redaction, and why the gate forgives what it does1920## Quick checks2122Run the full CI pipeline:2324```bash25make check26```2728This runs deps, format, lint, test, and build in sequence. Fix any issues before committing.2930## Individual steps3132If you need to run steps individually:3334```bash35make deps # install prerequisites (goimports, golangci-lint)36make format # goimports + gofmt37make lint # golangci-lint38make test # go test with race detection and coverage39make build # build binary to bin/ynh40```4142Target a specific package:4344```bash45make test FILE=./cmd/ynh46make test FILE=./internal/assembler47```4849## Before committing50511. Run `make check` - all steps must pass522. Check test coverage - new features should include tests533. Review the test matrix in `references/architecture.md` if touching assembler/resolver logic5455## Manual testing5657After code changes, verify against the relevant tutorial in `docs/tutorial/`.58`docs/tutorial/manual-test-plan.md` adds edge cases the tutorials do not cover.5960Tutorial filenames are descriptive, not numbered — do not cite them by number.6162| Package / area | Tutorial |63|---|---|64| `cmd/ynh` (install, run, ls, uninstall) | `first-harness.md` |65| `internal/vendor`, `internal/symlink` | `vendors-and-symlinks.md` |66| `internal/resolver` (includes, Git sources) | `composition.md` |67| `internal/assembler` (delegates) | `delegation.md` |68| `internal/exporter` | `export.md` |69| `internal/marketplace` | `marketplace.md` |70| `internal/registry`, `internal/sources` | `registry-and-discovery.md` |71| `cmd/ynd` (create, lint, validate, fmt, compress) | `developer-tools.md` |72| `cmd/ynd` (preview, compose, diff) | `developer-preview.md` |73| Docker image build | `docker-image.md` |74| Hooks | `hooks.md` |75| MCP servers | `mcp-servers.md` |76| Profiles | `profiles.md` |77| Focus | `focus.md` |78| Project-local config | `project-local-config.md` |79| `internal/clischema`, `internal/jsonschema` | `structured-output.md` |80| `ynh include` editing | `include-editing.md` |81| `internal/namespace`, `internal/migration` | `namespacing-and-migration.md` |82| `internal/plugin` (sensor declarations) | `sensors.md` |83| `internal/gate`, `internal/baseline` | `check.md` |84| `internal/agent` | `agent-loop.md` |85| `internal/freshness`, shadow mode | `shadow-mode.md` |8687Run the relevant tutorial steps end-to-end before committing. Build first with88`make build` so the binaries reflect your changes. The tutorials use `/tmp/` as89a scratch directory; the `evals` agent has the isolation rules.9091## Common issues9293- **Tool not found**: The Makefile uses full paths to GOPATH/bin for go-installed tools. Run `make deps` if tools are missing.94- **Lint errors**: `errcheck` is strict - all returned errors must be handled, even in tests95- **Test isolation**: Always use `t.TempDir()` and `t.Setenv("YNH_HOME", "")` to avoid leaking state
eyelock