Skip to content

Contributing

We welcome contributions of all kinds — bug reports, documentation improvements, new SQL training examples, and feature additions.

Ways to Contribute

  • Report a Bug

    Found a case where the API generates wrong SQL or crashes?
    Open a GitHub Issue with reproduction steps.

  • Add Training Data

    Verified SQL queries that we haven't seen before are the highest-value contribution.
    See the Training Best Practices guide.

  • Improve Docs

    Found a typo, outdated example, or missing explanation?
    Every page has an "Edit this page" link in the top-right corner.

  • Submit Code

    New endpoint, performance improvement, or bug fix? Fork → branch → PR.

Development Setup

1. Fork and Clone

git clone https://github.com/your-org/dbn-analytics-poc.git
cd dbn-analytics-poc

2. Create a Virtual Environment

python3 -m venv venv && source venv/bin/activate

python -m venv venv; .\venv\Scripts\Activate.ps1

3. Install Dependencies

pip install -r requirements.txt
pip install mkdocs-material  # for editing documentation

4. Set Up .env

cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

5. Run the API

uvicorn main:app --reload

6. Run the Docs

mkdocs serve

Code Standards

Area Standard
Style PEP 8 — use a linter (e.g., ruff)
Type hints Required on all public functions and class attributes
Docstrings Required on all public methods
Schemas All new endpoints must have Pydantic v2 request/response models
Imports Absolute imports only; no wildcard imports

Pull Request Process

  1. Create a branch — name it descriptively: feat/azure-sql-connector, fix/training-delete-bug
  2. Write your changes — keep PRs focused; one feature or fix per PR
  3. Update docs — if your PR changes API behaviour, update the relevant docs page
  4. Open a PR against main with a clear description of what and why
  5. Review — a maintainer will review within 48 hours

SQL Training Examples

If contributing new training examples (POST /api/v1/training/sql), every SQL pair must have been run against the real database and verified to return correct results. Include the question, SQL, and a sample of the output in your PR description.

Reporting Issues

When opening an issue, please include:

  • Environment: OS, Python version, relevant package versions (pip freeze | grep vanna)
  • Steps to reproduce — exact curl command or Python snippet
  • Actual behaviour — what happened
  • Expected behaviour — what you expected
  • Logs — any relevant output from uvicorn console