Contributing

Ground Rules

AnyVali is a portability-first project. Contributions are expected to preserve deterministic behavior across SDKs and across schema import/export boundaries.

If a change is only correct in one language, it is usually incomplete.

Before You Start

• Open an issue for large features, portability changes, or public API changes.
• Keep pull requests focused. Avoid mixing refactors, feature work, and unrelated formatting.
• Prefer spec-first changes for any behavior that affects multiple SDKs.

Required Conditions For Contributions

All contributions must satisfy these conditions:

1. Behavior changes must be reflected in the spec, docs, or corpus when applicable.
2. New features must include tests.
3. Bug fixes must include a regression test when practical.
4. Portable behavior must not silently diverge between SDKs.
5. New non-portable behavior must be explicitly documented as local-only or extension-based.
6. Breaking changes must be called out clearly in the pull request.
7. Generated artifacts, local caches, and dependency folders should not be committed unless intentionally tracked.

Commit Style

This repository uses conventional commits for release automation and changelog generation.

Examples:

feat(js): add record schema import
fix(python): validate default before returning parsed output
docs: tighten portability guide wording
chore(ci): add kotlin and cpp jobs

Use scopes when the change is specific to one SDK or subsystem.

Development Workflow

Use the root runner where possible:

./runner.sh install
./runner.sh build
./runner.sh test
./runner.sh ci

Run a single SDK if needed:

./runner.sh test go
./runner.sh build js

Testing Expectations

At minimum, contributors should run the relevant local test suite for the code they changed.

If a change affects the portable format, conformance corpus, parse semantics, or import/export behavior, run all impacted SDK suites before submitting.

Pull Request Checklist

• The change is scoped and explained clearly.
• Tests were added or updated.
• Relevant docs were updated.
• Public behavior changes are called out.
• Commit messages follow conventional commits.
• CI is expected to pass on supported platforms.

Coding Expectations

• Match existing style in the touched SDK.
• Keep APIs small and explicit.
• Prefer declarative, portable semantics over clever runtime-specific behavior.
• Do not introduce hidden coercions or lossy numeric conversions in portable flows.

License

By contributing, you agree that your contributions will be licensed under the MIT License in this repository.