Contributing to UQAL
UQAL is split across three repositories. Each has different rules about who can contribute and how.
Which repo should I contribute to?
| I want to… | Repo | Open to everyone? |
|---|---|---|
| Build a new database module | uqal-modules | ✓ Yes |
| Fix a bug in an existing community module | uqal-modules | ✓ Yes |
| Improve documentation | uqal-docs | via PR |
| Work on the core engine (parser, AST, CLI) | uqal-core | ✗ Team only |
uqal-modules — Open Community Contributions
Anyone can contribute a community module or fix bugs in existing ones.
How it works:
- Fork uqal-lang/uqal-modules
- Create a staging branch:
dev/community.<name> - Build your module in feature branches:
feat/community.<name>/... - Open a PR from
dev/community.<name>tomain - A maintainer reviews and approves before merge
All PRs are validated automatically by CI (structure, tests, coverage, docs). A maintainer approval is always required before anything is merged.
See the full guide: Community Workflow
uqal-core — Team Only
uqal-core is the engine that all modules run on. Development is restricted to members of the UQAL team to ensure stability and backwards compatibility.
Pull requests from outside the team will not be approved and will be closed.
If you want to work on uqal-core:
- Open an issue on uqal-core describing what you want to work on
- The maintainers will decide whether to invite you to the team as a
developer - Once added, you can create branches from
devand open PRs — every PR still requires maintainer approval before merge
Why is this restricted?
Changes to uqal-core affect every module. A breaking change in the parser or module interface can break all community modules at once. We keep the contributor circle small to control that risk.
uqal-docs — Maintainer Managed
Documentation is updated automatically when modules are published. Manual changes (fixing typos, improving wording) are handled by maintainers.
If you spot an error in the docs, open an issue on uqal-docs and a maintainer will fix it.
Reporting Bugs
- Bug in a community module → uqal-modules issues
- Bug in the core engine → uqal-core issues
- Security vulnerability → see SECURITY.md
Where to Start
- Architecture — how UQAL works internally
- Module Development — build a new database module
- Extension Modules — add capabilities to an existing module
- Module Standards — required structure,
module.jsonschema, test requirements - Community Workflow — branch strategy, PR rules, auto-versioning, publishing