Skip to content

Contributing to FletX

Thank you for your interest in FletX! 🎉 This comprehensive guide outlines how to contribute effectively.

📋 Table of Contents

  1. Getting Started
  2. Project Structure
  3. Development Workflow
  4. Code Conventions
  5. Testing & Quality
  6. Documentation
  7. Reporting Bugs
  8. Feature Proposals
  9. Code of Conduct

🚀 Getting Started

Local Setup

  1. Clone the repository

    Bash
    1
2
    git clone https://github.com/AllDotPy/FletX.git
cd FletX

  2. Set up virtual environment (Recommended: UV)

    Bash
    1
2
3
4
    pip install uv
uv venv
source venv/bin/activate  # Linux/Mac
# or .\venv\Scripts\activate  # Windows

  3. Install dependencies

    Bash
    1
    uv pip install -e .[dev]  # Development mode

  4. Verify installation

    Bash
    1
    pytest tests/

🏗 Project Structure

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
.
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── architecture.svg
├── docs/
├── examples/
├── fletx
│   ├── __init__.py
│   ├── app.py
│   ├── core
│   │   ├── __init__.py
│   │   ├── controller.py
│   │   ├── di.py
│   │   ├── effects.py
│   │   ├── factory.py
│   │   ├── navigation
│   │   │   ├── guards.py
│   │   │   ├── middleware.py
│   │   │   └── transitions.py
│   │   ├── observer.py
│   │   ├── page.py
│   │   ├── route_config.py
│   │   ├── router.py
│   │   ├── state.py
│   │   ├── types.py
│   │   └── widget.py
│   ├── decorators
│   │   ├── controllers.py
│   │   ├── reactive.py
│   │   └── route.py
│   ├── utils
│   │   ├── __init__.py
│   │   ├── context.py
│   │   ├── exceptions.py
│   │   └── logger.py
│   └── widgets
│       ├── __init__.py
│       └── text.py
├── main.py
├── pyproject.toml
└── setup.py

🔄 Development Workflow

  1. Create a branch
    Branch from master with descriptive naming:

    Bash
    1
    git checkout -b feat/new-reactive-component

  2. Implement changes

  3. Keep commits atomic

  4. Document new features

  5. Run tests

    Bash
    1
2
    uv pip install -e .[test]
pytest tests/

  6. Submit a Pull Request

  7. Clearly describe changes
  8. Reference related issues
  9. Address code review feedback

✨ Code Conventions

Style Guide

  • Follow PEP 8 (88 chars max line length)
  • Type hints for all public functions
  • Google-style docstrings for key modules

Reactivity Pattern

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Good
class ReactiveButton(ft.ElevatedButton, FletXWidget):
    """ My Reactive Button which.... """

    def __init__(self, text: RxStr, **kwargs):
        super().__init__(**kwargs)
        # Create a reactive object
        self.rx_text: RxStr = RxStr('')
        # And bind it to self (@ft.ElevatedButton) text attribute
        self.bind('text', self.rx_text)

Widget Standards

  • Prefix reactive widgets with Reactive
  • Isolate state logic in dedicated classes

🧪 Testing & Quality

Running Tests

Bash
1
pytest tests/ --cov=fletx --cov-report=html

Quality Standards

  • Maintain >90% code coverage
  • All new widgets require:
  • Unit tests
  • Functional example
  • Documentation

📚 Documentation

Writing Docs

Python
1
2
3
4
5
6
7
class ReactiveText(ft.Text, FletXWidget):
    """Text widget with reactive value binding.

    Args:
        value: RxStr to bind to text value
        color: RxStr for text color (optional)
    """

Building Documentation

Bash
1
2
cd docs/
make html

🐛 Reporting Bugs

  1. Check existing issues for duplicates
  2. Include:
  3. Steps to reproduce
  4. Expected vs actual behavior
  5. FletX/Python versions
  6. Minimal reproducible example

💡 Feature Proposals

  1. Clearly describe the use case
  2. Suggest technical approach
  3. Outline potential impacts
  4. Attach mockups if applicable

🤝 Code of Conduct

We adhere to the Contributor Covenant Code of Conduct. By participating: - Be kind and open-minded - Respect differing viewpoints - Assume good faith

Thank you for helping build FletX! Together we're creating the best reactive framework for Flet. 🚀