Skip to main content

Development guide

This guide covers the development workflow, tools, and conventions for contributing to topo.

Topo CLI​

Prerequisites​

  • Go 1.26+

Building​

go build ./cmd/topo

Linting​

The project uses golangci-lint for Go code quality checks.

# Install golangci-lint
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1

# Run linter and formatter checks
golangci-lint run

# Run linter/formatter with auto-fix
golangci-lint run --fix

Testing​

The project uses Go's built-in support for unit testing to provide test coverage.

Container tests require OpenSSH and Docker running Linux containers. Some tests also require Podman. Test container images are built automatically.

From the repository root, opt in to SSH configuration when running container tests:

SETUP_TEST_SSH=1 go test ./...

This adds topo-test-* aliases to ~/.ssh/config (%USERPROFILE%\.ssh\config on Windows), preserving existing settings. Fixtures use separate files under ~/.ssh/topo-test-known-hosts/ instead of your normal known_hosts.

The configuration persists. Subsequent runs need only go test ./..., without the environment variable.

Container tests skip if the SSH setup is missing. Tests also skip when a required Docker or Podman executable is missing. Use go test -v ./... to see skip reasons.

Golden Files​

A subset of our e2e tests rely on "golden files" to assert CLI output against a known good state. These tests will fail when the CLI output has changed and can be updated in place with the UPDATE_GOLDEN environment variable when running the tests.

UPDATE_GOLDEN=1 go test ./e2e/...

While an output change is not necessarily breaking, it's worth reviewing the breaking change policy and ensuring the change is marked as breaking/non-breaking appropriately before approving.

Skills​

Public agent skills live under skills/.

To test skills from this checkout while developing them, install the local repository with npx skills. Choose symlinks when prompted if you want edits in this checkout to be reflected immediately.

npx skills add . --global

Each installable skill folder should be self-contained, but shared Topo Project context is maintained in skills/_shared/topo-project-context.md to avoid hand-edited drift across skills. After editing that shared context, update each skill's references/topo-project-context.md copy:

node scripts/sync-skill-context.js

Check that skill context references are current:

node scripts/sync-skill-context.js --check

Skill-specific instructions should stay workflow-focused. Put stable common vocabulary in the shared context, reference the current schema/docs for evolving spec details, and avoid copying the full specification into individual skills.

Docs​

Developing the docs​

Use the provided compose project to preview docs changes locally:

docker compose up

The documentation preview is available at http://localhost:3000 and automatically reloads when files change.

Updating the catalog schema​

The catalog schema version is declared by the go:generate directive in internal/catalog/catalog.go and copied into internal/catalog/catalog_schema_generated.go. Its major component also selects the catalog version used by Topo.

Generating the Go types requires Node.js 20 or newer, npx, and access to the internet. From the repository root, run:

go generate ./internal/catalog

The generator downloads the configured version's catalog.schema.json, generates the catalog Go types with the pinned Quicktype version, and rewrites internal/catalog/catalog_schema_generated.go. To use another schema release, update the directive in internal/catalog/catalog.go and rerun the command.

Commit the newly generated catalog schema types file and raise a PR to update the main branch.

Available catalog versions and schemas are published in the Topo Project Catalog Artifactory repository.