Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
228 lines (155 loc) · 7.24 KB

CONTRIBUTING.md

File metadata and controls

228 lines (155 loc) · 7.24 KB
Raw

Contributing to QWED

QWED = Query with Evidence and Determinism

Thank you for your interest in contributing! Before you start, please read this guide to understand QWED's philosophy and avoid common misunderstandings.

📚 Required Reading (Before Contributing)

File Why It Matters
README.md Understand what QWED is
QWED_RULES.md Canonical enforcement rules for contributors and tools
docs/architecture.md System design and engine architecture
CODE_OF_CONDUCT.md Community standards
SECURITY.md How to report vulnerabilities

🧠 Understanding QWED's Philosophy

The Core Principle: Deterministic First

QWED is NOT just another LLM wrapper. Our philosophy:

  1. LLMs are untrusted translators - They convert natural language to structured queries
  2. Symbolic engines are trusted verifiers - SymPy, Z3, SQLGlot, etc. do the actual verification
  3. Determinism is required - Given the same input, output must be identical every time
  4. LLM output is never proof - Models may assist with translation or enrichment, but they must not weaken deterministic enforcement

When contributor guidance and enforcement guidance appear to conflict, follow QWED_RULES.md as the authoritative source for boundary behavior.

✅ Approved Paths

Sensitive operations must go through approved wrappers — never bare calls:

Dangerous Operation Approved Path
eval() / exec() code_engine.safe_eval() / code_engine.safe_exec()
parse_expr() safe_parser.safe_parse_expr()
os.system() / subprocess.Popen() code_engine.safe_shell()

Direct calls to these dangerous functions outside their approved wrappers will be caught by the CI boundary gate (see scripts/check_boundary.py).

❌ Common Misunderstandings

Wrong Approach Correct Approach
"Let the LLM verify the math" Use SymPy to compute, LLM only translates
"Add more LLM prompts to fix edge cases" Add deterministic patterns/rules
"Cache LLM responses" Deterministic verification doesn't need caching
"Trust LLM confidence scores" Use symbolic proof verification
"The system prompt will prevent X" Add an explicit deterministic guard
"The model said it's correct" Verify with deterministic computation

🔧 Development Setup

# Clone the repo
git clone https://github.com/QWED-AI/qwed-verification.git
cd qwed-verification

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or .\venv\Scripts\activate on Windows

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

🎯 Current Focus (Phase 1: Logic Verification)

We are building symbolic execution capabilities. Here are the priority issues:

Priority Issue Description
🔴 High #15 CrossHair Integration Python-native symbolic execution
🟡 Medium #16 Bounded Model Checking Loop depth limits for path explosion
🟢 Easy Documentation improvements Help improve docs

Pick an issue labeled good first issue or help wanted to get started!

🚀 How to Contribute

1. Reporting Bugs

Open an issue with:

  • QWED version (pip show qwed)
  • Python version
  • Input that caused the bug
  • Expected vs actual output
  • Full traceback

2. Proposing Features

Before coding, open an issue to discuss:

  • What problem does it solve?
  • Does it require LLM or is it deterministic?
  • Which engine does it affect?

3. Submitting Pull Requests

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/qwed-verification.git

# 2. Create a branch
git checkout -b feat/your-feature

# 3. Make changes

# 4. Run tests
pytest tests/ -v

# 5. Commit with conventional commits
git commit -m "feat(engine): add capability X"

# 6. Push and create PR
git push origin feat/your-feature

4. Code Review Standards

To maintain high code quality and security, all Pull Requests (PRs) must undergo a rigorous review process:

  • Two-Person Review: All non-trivial changes (features, bug fixes, refactors) require validation from at least one maintainer other than the author.
  • Automated Checks: All CI checks (linting, testing, security scans) must pass.
  • Review Checklist:
    • Logic correctness and edge case handling
    • Test coverage (tests added for new features)
    • Security implications (no hardcoded secrets, safe input handling)
    • Documentation updates
    • Compliance with coding standards (PEP 8, type hints)

Self-merging is restricted to documentation fixes, minor typos, or urgent hotfixes by the BDFL.

Commit Message Format

type(scope): description

feat(math): add matrix determinant support
fix(sql): handle nested subqueries
docs: update architecture diagram
test: add edge cases for logic engine

📁 Repository Structure

qwed-verification/
├── src/qwed_new/
│   └── core/           # 🔴 Core verification engines
│       ├── *_verifier.py   # One file per engine
│       └── control_plane.py # Request routing
├── qwed_sdk/           # Python SDK
├── sdk-ts/             # TypeScript SDK
├── sdk-go/             # Go SDK
├── sdk-rust/           # Rust SDK
├── tests/              # Unit tests
├── examples/           # Usage examples
└── docs/               # Documentation

⚠️ What NOT to Contribute

These features are in a separate enterprise repo and not accepted here:

  • ❌ Audit logging / compliance exports
  • ❌ SSO / authentication systems
  • ❌ Multi-tenancy features
  • ❌ Telemetry / observability
  • ❌ Enterprise RBAC

If you're interested in enterprise features, contact us at rahul@qwedai.com.

📜 License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.

⚖️ Governance & Legal

Developer Certificate of Origin (DCO)

To contribute to this project, you must sign off on your commits, certifying that you have the right to submit the code under the project's license. This is done by adding a Signed-off-by line to your commit messages.

Signed-off-by: Random J. Developer <random@developer.example.org>

By signing off, you certify the following:

I certify that the contribution is original work, or I have the right to submit it under the open source license. I understand that my contribution and personal information (including name and email) will be permanently recorded in the project's commit history.

Build tools and bots may enforce this requirement. You can sign off commits automatically with git commit -s.

Project Governance

This project is governed under a BDFL model. See GOVERNANCE.md for details on decision making, roles, and continuity planning.

💬 Questions?

  • Open an issue with the question label
  • Join discussions in GitHub Discussions
  • Email: rahul@qwedai.com