[READ-ONLY] Mirror of https://github.com/glacials/winter. a thoughtful static website generator for long-lasting content twos.dev/winter
winter AGENTS.md
2.2 kB · 37 lines
Markdown
at main

Repository Guidelines #

Project Structure & Module Organization #

  • cmd/: Cobra-based CLI commands (build, serve, init, freeze, test, etc.).
  • document/: Core build pipeline (config, parsing, templates, images, URIs).
  • cliutils/: Small CLI helpers (printing, prompts).
  • testdata/ and document/testdata/: Input/fixture files for tests.
  • main.go: Entrypoint wiring version info to the CLI.
  • .github/workflows/: CI running go test and a release build.

Build, Test, and Development Commands #

  • go test ./...: Run all unit tests. Add -race locally for data race checks.
  • go run . --help: Preview CLI usage; try commands like go run . build -s.
  • go build -o w .: Compile the CLI locally.
  • Versioned build (matches CI): go build -ldflags="-X 'main.version=$(git describe --tags --always)'" -o w ..
  • Hygiene: go fmt ./... and go vet ./... before sending PRs.

Coding Style & Naming Conventions #

  • Go formatting is canonical: run go fmt and keep imports tidy.
  • Prefer idiomatic, small packages and clear exported names (CamelCase); files use snake_case.go.
  • Errors: wrap with context (fmt.Errorf("doing X: %w", err)) and log via slog where appropriate.
  • Keep CLI flags consistent with existing ones (-v/--verbose, -q/--quiet).

Testing Guidelines #

  • Use the standard testing package; name files *_test.go and tests TestXxx.
  • Favor table-driven tests; place fixtures under testdata/.
  • Ensure deterministic outputs (templates, image ops) and cover edge cases.
  • Run go test ./... (and -race locally) before committing.

Commit & Pull Request Guidelines #

  • Commits: imperative, concise subject (≤72 chars). Examples: fix reloader nil channel, feat: add build summary.
  • Reference issues/PRs when applicable ((#123)). Squash trivial fixups.
  • PRs: include a clear description, reproduction or motivation, test coverage for changes, and notes on docs updates (README/CLI help) if behavior changes.

Architecture Overview #

  • CLI is composed in cmd/root.go; core build logic lives in document/ (via Substructure.ExecuteAll).
  • build -s serves dist/ on localhost:8100 with live reload.