Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
362 lines (257 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

362 lines (257 loc) · 10.4 KB

Contributing to DAZZLE

Thank you for your interest in contributing to DAZZLE! We're excited to have you here. Whether you're fixing a bug, adding a feature, improving documentation, or just sharing ideas, your contributions make DAZZLE better for everyone.

🌟 Ways to Contribute

We welcome all kinds of contributions:

  • 🐛 Bug Reports: Found something broken? Let us know!
  • 💡 Feature Requests: Have an idea? Share it!
  • 📝 Documentation: Help others understand DAZZLE
  • 🔧 Code: Fix bugs or implement new features
  • 🎨 Examples: Create example projects showcasing DAZZLE
  • 🧪 Tests: Improve test coverage
  • 💬 Discussions: Help answer questions and support users

🚀 Getting Started

Development Setup

  1. Fork and Clone

    git clone https://github.com/manwithacat/dazzle.git
cd dazzle

  2. Set Up Python Environment

    # We recommend Python 3.11 or 3.12
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install Development Dependencies

    pip install -e ".[dev]"

  4. Install Pre-commit Hooks (recommended)

    pip install pre-commit
pre-commit install

    This will automatically run linting, formatting, and type checking before each commit.

  5. Verify Installation

    dazzle --help
pytest

Making Your First Contribution

  1. Pick an Issue: Browse open issues or create a new one
  2. Comment: Let others know you're working on it
  3. Branch: Create a feature branch (git checkout -b feature/amazing-feature)
  4. Code: Make your changes
  5. Test: Ensure tests pass
  6. Commit: Write clear commit messages
  7. Push: Push to your fork
  8. PR: Open a pull request

📋 Development Workflow

Before You Start

  • Check Existing Work: Search issues and PRs to avoid duplicates
  • Discuss Big Changes: For major features, open an issue first to discuss approach
  • Read the Specs: Check devdocs/ for relevant specification documents

Code Quality

We maintain high code quality standards:

# Run all pre-commit hooks manually
pre-commit run --all-files

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/dazzle --cov-report=html

# Type checking
mypy src/dazzle

# Linting
ruff check src/ tests/

# Format code
ruff format src/ tests/

Note: If you installed pre-commit hooks, these checks will run automatically on git commit.

Testing

  • Write Tests: All new features should include tests
  • Validate Examples: Run python tests/build_validation/validate_examples.py
  • Manual Testing: Test with real DSL files in examples/

Commit Messages

Write clear, descriptive commit messages:

Add hover documentation for entity fields

- Implement rich markdown formatting for field types
- Include field modifiers and constraints in hover
- Add examples for common field patterns

Closes #123

🎯 Contribution Ideas

Here are some areas where we'd love your help:

🔰 Good First Issues

Perfect for newcomers:

  • Add More Field Types: Extend DSL with new field types (e.g., url, phone, color)
  • Improve Error Messages: Make validation errors more helpful
  • Add DSL Examples: Create example projects for common use cases
  • Documentation: Fix typos, clarify concepts, add diagrams
  • Tests: Increase test coverage for edge cases

🔌 Backend Development

Create new backends to generate different outputs:

  • Django Backend: Generate Django models, admin, views

    • Models with proper field mappings
    • Admin configuration
    • REST API views
    • Migrations generation

  • FastAPI Backend: Generate FastAPI endpoints

    • Pydantic models from entities
    • CRUD endpoints for each entity
    • SQLAlchemy models
    • API documentation

  • Prisma Backend: Generate Prisma schema

    • Schema.prisma file generation
    • Relationship mappings
    • Migration support

  • GraphQL Backend: Generate GraphQL schema

    • Type definitions
    • Resolvers
    • Mutations for CRUD operations

  • React/Next.js Frontend: Generate UI components

    • Form components for surfaces
    • List views
    • Detail views
    • TypeScript types

💡 IDE Support

Expand IDE support beyond VSCode:

  • JetBrains Plugin: PyCharm, IntelliJ IDEA support
  • Emacs Mode: Major mode for Emacs
  • Vim Plugin: Syntax highlighting and LSP support
  • Web IDE: Browser-based DAZZLE editor with live preview

🎨 LSP Enhancements

Improve the Language Server Protocol implementation:

  • Code Actions: Quick fixes for common errors
  • Refactoring: Rename entities, extract modules
  • Code Lens: Show field counts, surface usage
  • Semantic Highlighting: Better syntax coloring
  • Snippets: Templates for common patterns
  • Validation Rules: Additional lint checks

📊 Tooling & Analysis

Build tools to help developers:

  • DSL Formatter: Auto-format DSL files
  • Migration Tool: Generate migrations between DSL versions
  • Visual Editor: Drag-and-drop entity designer
  • Dependency Graph: Visualize module relationships
  • Coverage Report: Track which entities/surfaces are tested
  • Performance Profiler: Identify slow validation rules

🌐 Integration & Services

Add support for popular services:

  • Auth Providers: Auth0, Firebase, Supabase presets
  • Databases: Connection presets for PostgreSQL, MySQL, MongoDB
  • Cloud Platforms: AWS, GCP, Azure deployment configs
  • API Services: Stripe, SendGrid, Twilio integrations
  • Monitoring: Sentry, DataDog, New Relic instrumentation

🧪 Testing & Quality

Improve testing infrastructure:

  • LLM Context Testing: Validate that LLMs can understand DAZZLE projects
  • Performance Benchmarks: Track build times and memory usage
  • Mutation Testing: Ensure test quality with mutation testing
  • E2E Tests: Full workflow testing from DSL to deployment
  • Fuzzing: Random DSL generation for robustness testing

📚 Documentation & Learning

Help others learn DAZZLE:

  • Video Tutorials: Screen recordings showing DAZZLE workflows
  • Interactive Tutorial: Step-by-step guide in the browser
  • Best Practices Guide: Patterns and anti-patterns
  • Migration Guides: Moving from other tools to DAZZLE
  • Case Studies: Real-world DAZZLE applications
  • Comparison Guide: DAZZLE vs Prisma, Terraform, etc.

🚀 Infrastructure & DevOps

Make deployment easier:

  • Docker Images: Pre-built images for quick starts
  • Terraform Modules: Infrastructure as code
  • GitHub Actions: Ready-to-use CI/CD workflows
  • Kubernetes Configs: K8s deployment manifests
  • Monitoring Stack: Prometheus, Grafana dashboards

🏗️ Architecture Overview

Understanding DAZZLE's architecture helps you contribute effectively:

Core Components

src/dazzle/
├── core/           # Core language implementation
│   ├── parser.py   # DSL parser (lark-based)
│   ├── ir.py       # Intermediate representation
│   ├── linker.py   # Module resolution and linking
│   └── lint.py     # Semantic validation
├── backends/       # Code generators
│   ├── openapi/    # OpenAPI 3.0 backend
│   └── base.py     # Backend interface
├── lsp/            # Language Server Protocol
│   └── server.py   # LSP implementation
└── cli/            # Command-line interface
    └── main.py     # CLI entry point

Key Concepts

  • Parser: Converts .dsl text to AST using Lark grammar
  • IR (Intermediate Representation): Type-safe Python models (Pydantic)
  • Linker: Resolves cross-module references and builds AppSpec
  • Validator: Checks semantic rules and constraints
  • Backends: Transform IR into concrete artifacts
  • Stacks: Coordinated multi-backend generation

See devdocs/README.md for detailed documentation.

💬 Communication

Getting Help

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions, ideas, show-and-tell
  • Documentation: Check docs/ and devdocs/

Code Review

All contributions go through code review:

  • Be patient and respectful
  • Respond to feedback constructively
  • Iterate based on suggestions
  • Ask questions if anything is unclear

We aim to review PRs within 48 hours.

📜 Coding Standards

Python Code

  • Style: Follow PEP 8, enforced by ruff
  • Type Hints: Use type annotations everywhere
  • Docstrings: Document public APIs with Google-style docstrings
  • Imports: Group by standard library, third-party, local
  • Naming: snake_case for functions/variables, PascalCase for classes

DSL Grammar

When modifying the grammar (src/dazzle/core/grammar.lark):

  • Keep syntax minimal and consistent
  • Add examples for new features
  • Update documentation
  • Consider LLM tokenization efficiency

Tests

  • Unit Tests: Test individual functions and classes
  • Integration Tests: Test component interactions
  • E2E Tests: Test full workflows
  • Naming: test_<feature>_<scenario>_<expected_result>

Documentation

  • User Docs (docs/): For DAZZLE users
  • Dev Docs (devdocs/): For contributors
  • Code Comments: Explain why, not what
  • Examples: Show real-world usage

🎉 Recognition

Contributors are recognized in:

  • Release notes
  • CONTRIBUTORS.md file
  • Git history
  • Our gratitude! 🙏

⚖️ License

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

🤝 Code of Conduct

Be kind, respectful, and professional. We're all here to learn and build something great together.

Expected Behavior

  • Welcome newcomers
  • Be patient with questions
  • Give constructive feedback
  • Celebrate successes
  • Assume good intentions

Unacceptable Behavior

  • Harassment or discrimination
  • Trolling or insulting comments
  • Personal attacks
  • Unwelcome sexual attention
  • Publishing others' private information

📞 Contact

Thank you for contributing to DAZZLE! Every contribution, no matter how small, makes a difference. We're excited to see what you'll build! 🚀