Development Setup

Complete guide to setting up a RING-5 development environment.

Prerequisites

Python 3.12+
Git
Virtual environment tool (venv)
Code editor (VS Code recommended)

Initial Setup

1. Clone Repository

git clone https://github.com/USER/RING-5.git
cd RING-5

2. Create Virtual Environment

python3 -m venv python_venv
source python_venv/bin/activate  # Linux/macOS
# python_venv\Scripts\activate  # Windows

3. Install Development Dependencies

make dev
# Installs: pytest, mypy, black, flake8, and project dependencies

Project Structure

RING-5/
├── src/                    # Source code
│   ├── parsers/           # Data layer (parsing)
│   ├── plotting/          # Presentation layer (plots)
│   └── web/               # Web interface
├── tests/                  # All tests
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── e2e/               # End-to-end tests
├── docs/                   # Documentation
├── portfolios/             # Saved portfolios
└── Makefile               # Build commands

Development Workflow

1. Create Feature Branch

git checkout -b feature/my-feature

2. Make Changes

Edit code with your editor. Follow architecture guidelines in Architecture.md.

3. Run Tests

# All tests
make test

# Specific test file
pytest tests/unit/test_my_feature.py -v

# With coverage
pytest --cov=src tests/

4. Type Check

# Check all code
mypy src/ --strict

# Check specific file
mypy src/module/file.py --strict

5. Format Code

# Format all code
black src/ tests/

# Check formatting
black --check src/ tests/

6. Lint Code

flake8 src/ tests/

Running the Application

Development Mode

streamlit run app.py

With Auto-Reload

Streamlit auto-reloads on file changes.

Debug Mode

Add debug prints or use Python debugger:

import pdb; pdb.set_trace()

Common Development Tasks

Adding a New Shaper

Create shaper class in src/web/services/shapers/
Register in ShaperFactory
Add UI component in src/web/ui/components/shapers/
Write tests in tests/unit/test_shapers.py

See Adding-Shapers.md.

Adding a New Plot Type

Create plot class in src/plotting/types/
Inherit from BasePlot
Implement create_figure()
Register in PlotFactory
Write tests

See Adding-Plot-Types.md.

Adding a New Page

Create page module in src/web/pages/
Define render function
Add to navigation in app.py
Write UI tests

Testing

Running Tests

# All tests
pytest

# Specific category
pytest tests/unit/
pytest tests/integration/

# With coverage report
pytest --cov=src --cov-report=html tests/
# Opens htmlcov/index.html

Writing Tests

Follow TDD approach:

Write failing test
Implement feature
Test passes
Refactor

See Testing-Guide.md.

Code Quality

Type Checking

All code must pass strict type checking:

mypy src/ --strict

Requirements:

Type hints on all functions
No implicit Any
No untyped defs

Code Formatting

Use Black for consistent formatting:

black src/ tests/

Settings: Default Black configuration (88 char line length).

Linting

Flake8 checks for style issues:

flake8 src/ tests/

Best Practices

Follow Architecture: Maintain layer separation
Write Tests First: TDD approach
Type Everything: Strict typing mandatory
Document Why: Explain non-obvious decisions
Keep PRs Small: Focused, reviewable changes
Run All Checks: Before committing

Troubleshooting

Import Errors

Ensure virtual environment is activated and dependencies installed.

Test Failures

Check if changes broke existing tests. Fix tests or code as needed.

Type Errors

Add missing type hints or fix type inconsistencies.

Next Steps

Testing: Testing-Guide.md
Adding Features: Adding-Plot-Types.md, Adding-Shapers.md
Contributing: ../CONTRIBUTING.md