Skip to main content

Contributing Guide

Welcome! We're excited that you want to contribute to Ody's Rope. This guide will help you get started.

Development Setup​

Prerequisites​

  • Python 3.13+ (match Spaceship cPanel runtime)
  • Node.js 20+ (for documentation)
  • Git

Clone the Repository​

git clone https://github.com/your-org/StarterAlgo.git
cd StarterAlgo

Python Environment​

# Create virtual environment
python -m venv venv

# Activate (Windows)
.\venv\Scripts\activate

# Activate (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Run the Application​

python app.py

Project Structure​

StarterAlgo/
├── app.py                 # Main Flask application
├── config.py              # Configuration settings
├── db/                    # Database models and repositories
├── auth/                  # Authentication (WorkOS)
├── alembic/               # Database migrations
├── templates/             # HTML templates
├── webapp/                # Web application pages
├── static/                # Static assets (JS, CSS, images)
├── docs/                  # Documentation (source)
├── website/               # Docusaurus documentation site
└── trading-systems/       # Trading strategy documentation

Making Changes​

1. Create a Branch​

git checkout -b feature/your-feature-name

2. Make Your Changes​

  • Follow existing code style
  • Add comments for complex logic
  • Update documentation if needed

3. Test Your Changes​

# Run the application
python app.py

# Check for errors in logs
tail -f logs/app.log

4. Commit Your Changes​

git add .
git commit -m "feat: add your feature description"

We use Conventional Commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes (formatting)
  • refactor: - Code refactoring
  • test: - Adding tests

5. Push and Create PR​

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Code Style​

Python​

  • Follow PEP 8
  • Use type hints where possible
  • Document functions with docstrings
def calculate_position_size(
    capital: float,
    target_risk: float,
    instrument_risk: float,
    price: float
) -> int:
    """
    Calculate the recommended position size.
    
    Args:
        capital: Total trading capital
        target_risk: Target risk percentage (e.g., 0.12)
        instrument_risk: Instrument volatility (e.g., 0.18)
        price: Current price per share
    
    Returns:
        Number of shares to purchase
    """
    notional = capital * target_risk / instrument_risk
    return int(notional / price)

JavaScript​

  • Use ES6+ syntax
  • Add JSDoc comments for functions
  • Use meaningful variable names

Database Migrations​

When changing database models:

# Create a new migration
alembic revision --autogenerate -m "description of change"

# Apply migrations
alembic upgrade head

Documentation​

See docs/DOCUSAURUS_DOCUMENTATION_GUIDE.md in the repository root for how to update this documentation site.

Questions?​

  • Open an issue for bugs or feature requests
  • Check existing issues before creating new ones
  • Be respectful and constructive in discussions