Contributing Guide

Thank you for your interest in contributing to Streamlit Lightweight Charts Pro!

Development Setup

Clone the repository:

git clone https://github.com/nandkapadia/streamlit-lightweight-charts-pro.git
cd streamlit-lightweight-charts-pro

Install Python dependencies:

pip install -e ".[dev,test]"

Install frontend dependencies:

cd streamlit_lightweight_charts_pro/frontend
npm install

Install pre-commit hooks:

pip install pre-commit
pre-commit install

Code Standards

Python

Style: Google-style docstrings
Line length: ≤99 characters
Formatters: isort, autoflake, black, ruff
Type hints: Required for all public APIs
Docstrings: Required for all modules, classes, functions

def example_function(param: str, value: int) -> bool:
    """Short one-line summary.

    Longer description if needed. Explain the purpose, behavior,
    and any important details.

    Args:
        param: Description of param.
        value: Description of value.

    Returns:
        Description of return value.

    Raises:
        ValueError: When value is negative.

    Example:
        ```python
        result = example_function("test", 42)
        ```
    """
    if value < 0:
        raise ValueError("Value must be non-negative")
    return True

TypeScript

Style: Google-style JSDoc/TSDoc
Line length: ≤100 characters
Formatters: prettier, eslint
Type annotations: Required for all exports
JSDoc: Required for all exported functions/classes

/**
 * Example function with comprehensive documentation.
 *
 * @param param - Description of param
 * @param value - Description of value
 * @returns Description of return value
 * @throws {Error} When value is negative
 *
 * @example
 * ```typescript
 * const result = exampleFunction("test", 42);
 * ```
 */
export function exampleFunction(param: string, value: number): boolean {
    if (value < 0) {
        throw new Error("Value must be non-negative");
    }
    return true;
}

Testing

Python Tests

Run Python tests with pytest:

# Run all tests
pytest

# Run with coverage
pytest --cov=streamlit_lightweight_charts_pro

# Run specific test file
pytest tests/test_chart.py

# Run with markers
pytest -m unit
pytest -m integration

TypeScript Tests

Run TypeScript tests with Vitest:

cd streamlit_lightweight_charts_pro/frontend

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test
npm test -- colorUtils.test.ts

Pre-commit Hooks

Pre-commit hooks automatically run on every commit to ensure code quality.

Install:

pip install pre-commit
pre-commit install

Run manually:

# Run on all files
pre-commit run --all-files

# Run specific hook
pre-commit run black --all-files

Hooks include:

Python: isort, autoflake, black, ruff, pydocstyle
TypeScript: prettier, eslint, tsc, JSDoc validator
General: trailing whitespace, large files, merge conflicts

Pull Request Process

Create a branch:

git checkout -b feature/your-feature-name

Make changes following code standards
Write tests for new functionality
Run formatters and linters:

# Python
isort .
autoflake --in-place --remove-unused-variables --remove-all-unused-imports -r .
black .
ruff check --fix .

# TypeScript
cd streamlit_lightweight_charts_pro/frontend
npm run lint
npm run format

Run tests:

pytest
cd streamlit_lightweight_charts_pro/frontend && npm test

Commit changes:

git add .
git commit -m "feat: add new feature"

Push and create PR:

git push origin feature/your-feature-name

Commit Message Convention

Use conventional commits:

feat:: New feature
fix:: Bug fix
docs:: Documentation changes
style:: Code style changes (formatting)
refactor:: Code refactoring
test:: Test additions or changes
chore:: Build process or tooling changes

Examples:

feat: add support for histogram series
fix: resolve color validation bug
docs: update API reference for renderChart
test: add tests for color utilities

Code Review

All submissions require review. We review for:

Functionality: Does it work as intended?
Tests: Are there adequate tests?
Documentation: Is it well-documented?
Code quality: Does it follow our standards?
Performance: Are there performance implications?

Reporting Bugs

Report bugs via GitHub Issues.

Include:

Description: Clear description of the bug
Reproduction: Minimal code to reproduce
Expected behavior: What should happen
Actual behavior: What actually happens
Environment: Python version, OS, package version

Feature Requests

Feature requests are welcome! Open an issue with:

Use case: Why is this feature needed?
Proposed solution: How should it work?
Alternatives: Other approaches considered
Examples: Example usage code

Questions?

Open a GitHub Discussion
Review existing documentation
Check closed issues for similar questions