Contributor documentation

For people (human or LLM) implementing or maintaining a sovdev-logger language port — the API contract, field definitions, and design rationale every implementation must follow. Not for people just using the library; see Using sovdev-logger for that.

Start here

• Implementation guide — the end-to-end process: contract → TypeScript → anti-patterns → implement → compare-with-master.sh

Core documents

• Design principles — core philosophy and key design decisions
• OpenTelemetry SDK guide — OpenTelemetry SDK differences between languages
• API contract — the public API every language MUST implement
• Development loop — the iterative edit/lint/build/validate workflow

Supporting documents

• Field definitions — every log field, its type, and when it's present
• Implementation patterns — required patterns (snake_case, directory structure)
• Error handling — exception handling, credential removal, stack trace limits
• Environment configuration — environment variables, DevContainer setup, toolchain
• Test scenarios — test scenarios and verification procedures
• Anti-patterns — the mistakes every prior implementation attempt has actually made
• Test program: company lookup — the E2E test every implementation must pass
• Code quality — linting standards and quality rules

Testing

• Testing backends — how to stand up a real OTLP backend (starting with UIS) and point a language's E2E test at it

Releasing

• Publishing — how to release each language's package to its registry, one language at a time. So far: TypeScript (sovdev-logger on npm).

Functional code (not migrated — lives in the repo)

tools/ — schemas, validators, and the backend-specific query/comparison scripts (including compare-with-master.sh, the actual completion gate) — is functional code, not documentation. See tools/README.md for how it's organized (by OTLP backend: local UIS, Grafana Cloud, and future backends).