Contributing ¶

Cicadel is experimental. Start with a focused issue or change and describe the behavior you want to improve.

Work locally ¶

Use the Go version declared in go.mod and PostgreSQL 18 for integration tests. Read the repository’s AGENTS.md for project scope and contribution requirements. PostgreSQL is the only supported database.

The architecture guide describes package boundaries. The testing guide explains application fixtures and database-backed tests.

Documentation ¶

Edit the Markdown guides in docs/ or the relevant module README. The documentation website imports these files during its Hugo build, so fixes stay shared between GitHub and the published site.

See the website authoring instructions for local builds, navigation and release snapshots.

Verify changes ¶

Run the checks in all applicable .github/workflows/ workflows before pushing. Include nested Go modules and real PostgreSQL integration tests. UI changes require the matching Cicadel CLI’s ui build and ui check --json; commit authored and generated files together.

Keep changes focused. Do not stage unrelated work in a shared checkout. Report validation results and known limitations with your change.

Update the documentation site ¶

Edit source guides in docs/; write for developers building applications, with short explanations, working code and useful agent prompts. Put framework design and implementation history in the separate framework section.

Follow the website authoring guide for navigation, LLM exports, version snapshots and local checks. GitHub Actions builds and validates all static assets on pull requests, then publishes the verified site automatically when changes reach main. Do not edit generated website/public/ files or deploy from a personal machine as part of the normal authoring workflow.