Contributing to Vernac

Start with the repository contribution guide for issue reports, local verification and pull requests.

User documentation starts at the documentation home. This section is for language/tooling contributors. Build with JDK 25 and Maven 3.9+; generated application code retains its Java 21 target.

mvn clean verify

Standalone examples have their own POMs and checks. PostgreSQL tests need explicit disposable-database configuration and must not be counted as passed when skipped. Release acceptance also includes installation of the packaged IntelliJ plugin.

Learn from the IntelliJ integration

Lessons learned collects reusable engineering guidance on DSL/Java injection, resolution versus completion, native references, debugging, editor recovery and test boundaries. It includes a design checklist for a future SQLJ plugin. These are contributor notes, not additional language guarantees. For a guide across all documentation, use the documentation map.

Implementation and decisions

Compiler architecture: shared resolution, names and generation.
Feature review checklist: purpose, quality, diagnostics and tooling.
Generated output ownership: reconciliation and failure boundaries.
Shared Java implementation contract: nullable parameters, implementation targets and erased overload checks.
Validation delegates: access views and Java projection.
Entity changes and candidate-state design: current direct mutation and explicitly deferred alternatives.
LSP workspace analysis, embedded Java, Java navigation.
Schema tooling and scalar mapping decisions.
Event delivery and ports implementation.

Current priorities

Platform roadmap: IDE depth, language consistency, standard adapters, Kafka replication, HTML fragment composition and the separate SaaS project.

Modeling follow-up

DDD modeling roadmap: aggregate protection, concurrency-safe uniqueness, reusable rules, factories and domain variants.
Ubiquitous-language proposal: implemented initial term/hover/glossary support, with broader vocabulary and AI work deferred.

Project maintenance

Documentation ownership and validation
Deep IntelliJ integration roadmap: cross-language refactoring and debugger integration (implemented) and refactoring follow-up.
Versioned module completion: implemented scope, regression entrypoints and operational boundaries.
Capabilities and usecase authorization: future SaaS policy and reusable capability design on the implemented module system.
Consolidation status
Pagination implementation sequence: runtime foundation and remaining repository/Result/HTTP work.
0.4.0 release plan
0.5.0 release preparation
Release operations

Implementation notes explain mechanisms and trade-offs. They do not override the specification. Historical patch progress belongs in Git history; keep unresolved design decisions with an explicit status and rationale.

Native debugger implementation

The debugger implementation record documents build-time source mappings, Java-backed Vernac breakpoints and the installed-IDE acceptance walkthrough.

AI content disclosure review for vernac.org: assessment notes for the site’s publication workflow; recheck if that workflow changes.
AI tools reference: concise build, schema and migration workflow for coding agents.
Editor declaration recovery: declaration-level recovery, strict build separation and source ranges.
Live value-object Java APIs: in-memory Java views before generation, ownership and scope boundaries.