Skip to content

contributing.md

Latest commit

 

History

History
162 lines (111 loc) · 2.96 KB

contributing.md

File metadata and controls

162 lines (111 loc) · 2.96 KB

Contributing to ezrules

Fast Path

If you already know the project, use this checklist:

  1. Fork and clone
  2. uv sync
  3. Initialize test DB
  4. Create branch
  5. Implement change + tests
  6. Run checks:
    • uv run poe check
    • full test suite (coverage command below)
  7. Update docs/README/whatsnew.md if user-facing behavior changed
  8. Open PR with clear description

1) Fork and Clone

git clone https://github.com/YOUR_USERNAME/ezrules.git
cd ezrules
git remote add upstream https://github.com/sofeikov/ezrules.git

2) Set Up Development Environment

uv sync
uv run ezrules init-db --auto-delete
uv run ezrules bootstrap-org --name test_org --admin-email admin@test_org.com --admin-password 12345678

When validating migrations directly (without re-initializing the full DB), apply the current head:

uv run alembic upgrade head

Create a feature branch:

git checkout -b feature/your-feature-name

3) Database Migration Workflow

For any schema change, migrations are required.

# after editing models
uv run alembic revision --autogenerate -m "describe schema change"

# apply latest migrations
uv run alembic upgrade head

Rules:

  • Do not use Base.metadata.create_all for schema management
  • Commit model changes and migration files together
  • Review autogenerated migrations before committing

4) Development Workflow

Run tests (required before PR)

--8<-- "snippets/backend-test-command.md"

Run quality checks (required before PR)

uv run poe check

Optional targeted debugging

uv run pytest tests/test_api_v2_rules.py -v
uv run pytest tests/test_api_v2_rules.py::test_create_rule_success -v

5) Code and Test Expectations

  • Keep imports at file top
  • Add type hints for new code
  • Use existing fixtures where possible
  • Prefer real DB interactions in tests over mocking
  • Ensure no failing tests before opening PR

6) Pull Request Checklist

Before submitting:

  1. All tests pass
  2. uv run poe check passes
  3. Documentation updated for behavior changes
  4. README.md updated when user-facing workflows changed
  5. whatsnew.md updated for notable changes

Suggested PR template:

## Description

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Full test suite passed
- [ ] Added/updated tests as needed

## Checklist
- [ ] Quality checks passed
- [ ] Docs updated

7) Review Expectations

Reviewers focus on:

  • correctness
  • tests and regression risk
  • readability and maintainability
  • security/performance impact
  • docs alignment

8) Where to Contribute

  • performance and query optimizations
  • rule-authoring usability
  • dashboards and analytics UX
  • documentation quality and examples

If proposing a major feature, open an issue first to align scope.

Questions

  • Open a GitHub issue
  • Check existing issues/PRs
  • Read relevant docs pages first