Hex-O-Spell Experiment

A pygame-based experiment that integrates GUI, egg headset, and data management components for an immersive experience.

Project Overview

This project combines three main components:

• GUI: Graphical user interface for interaction
• Egg Headset: EEG headset integration for brain-computer interface
• Data Manager: System for handling and processing data

Prerequisites

• Python 3.13 or higher
• pip for package management

Installation

1. Clone the repository:

   git clone <repository-url>
   cd hex-o-spell-experiment

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -U pip
   pip install -e .

For development:

pip install -e ".[dev]"

Development Setup

1. Install pre-commit hooks:

   pre-commit install

2. Run tests:

   pytest

3. Run the application:

   python src/main.py

Project Structure

hex-o-spell-experiment/
├── src/                    # Source code
│   ├── gui/                # GUI components
│   ├── egg_headset/        # EEG headset integration
│   └── data_manager/       # Data management system
├── tests/                  # Unit and integration tests
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests
├── pyproject.toml          # Project configuration
└── README.md               # This file

Testing

Unit tests are located in tests/unit/ and integration tests in tests/integration/.

Run all tests:

pytest

Run specific test category:

pytest -m unit
pytest -m integration

Linting and Formatting

Format code:

black src/ tests/

Check for linting issues:

flake8 src/ tests/

Check for type issues:

mypy src/

CI/CD and Code Quality

This project includes automated CI/CD pipelines that enforce code quality and ensure robust software delivery:

Quality Checks Performed

• Formatting: Checked with Black on every commit and PR
• Linting: Checked with Flake8 on every commit and PR
• Type Safety: Checked with MyPy on every commit and PR
• Testing: All tests must pass before merging (unit and integration tests)
• Security: Dependencies are scanned for vulnerabilities weekly
• Coverage: Test coverage reports are generated and uploaded to Codecov

GitHub Actions Workflows

The following GitHub Actions workflows are configured:

• Python CI (python-ci.yml): Runs formatting, linting, type checking, testing and coverage reporting
• Pre-commit Hooks (pre-commit.yml): Runs all pre-commit hooks for consistency
• Security Scanning (security-scan.yml): Scans dependencies for known vulnerabilities

Pre-commit Hooks

To run these checks automatically before each commit:

1. Install pre-commit hooks:

   pre-commit install

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

Setting Up Branch Protection (Required)

To enforce these quality checks, set up branch protection rules in GitHub:

1. Navigate to your GitHub repository
2. Go to the "Settings" tab
3. Click on "Branches" in the left sidebar
4. Under "Branch protection rules", click "Add rule"
5. Enter "main" as the branch name pattern (or your primary branch)
6. Select the following options:
   • Require pull request reviews before merging
     • Set "Required number of approvals" to at least 1 (or your preferred number)
   • Require status checks to pass before merging
     • Check "Require branches to be up to date before merging"
     • In "Status checks that are required", ensure the following are selected:
       • test (3.13) - From python-ci.yml workflow
       • pre-commit - From pre-commit.yml workflow
   • Require conversation resolution before merging

Once configured, these rules will prevent merging pull requests until all quality checks pass.