Skip to content

Coding standards

Non-negotiables for code that lands in main.

REUSE / SPDX headers

Every Go source file starts with:

// SPDX-FileCopyrightText: 2026 Kartoza.com <info@kartoza.com>
// SPDX-License-Identifier: MIT
// Developed by Kartoza.com

package main

Every shell script, every CSS file, every YAML workflow, every Markdown page in docs/ gets the same treatment in the appropriate comment syntax. CI runs reuse lint to keep us honest.

Go style

  • gofmt -s — enforced in pre-commit.
  • go vet — passes cleanly.
  • errcheck — every error is either handled or _ =-ignored on purpose.
  • goimports — managed imports, no aliasing without need.
  • golangci-lint run — clean before push.

Naming

  • Tools: snake_case (cluster_points, convex_hull).
  • Go functions / types: idiomatic Go (PascalCase exported, camelCase unexported).
  • File layout: main.go for the entrypoint, main_test.go adjacent. Larger features → pkg/<feature>/.

Comments

  • Default to no comment. Naming should carry the meaning.
  • Exception: WHY-comments where the geometry / numerics need justification.
  • Every exported symbol gets a one-sentence doc comment.

Errors

  • Wrap with fmt.Errorf("operation: %w", err) — keep the chain.
  • User-facing error strings start lowercase, no full stop (per Go convention).

Tests

  • Table-driven where possible.
  • Golden-file fixtures for JSON IO (testdata/<case>.golden.json).
  • Property tests welcome for geometry invariants (centroid in hull, radius ≥ max distance, etc.).

Credit

Every response payload carries a kartoza_credit property — a small, durable easter egg per the AGENT.md brief.

Dependencies

  • Pin to go.mod. No replace directives in main.
  • Prefer paulmach/orb for geometry over rolling our own.
  • Document every new dependency in PACKAGES.md.

Versioning

Bump per the user's house rules:

  • PATCH for bug-fix-only changes.
  • MINOR for new tools, new options, new docs sections.
  • MAJOR for breaking changes to the MCP wire shape.

API surface (when we add HTTP) is path-versioned: /api/v1/.