Code Guidelines

This page describes how to contribute code to ICOS-FL.

Setting Up Development Environment

  1. Fork the repository and clone it to your local machine:

    git clone https://github.com/yourusername/icos-fl.git
cd icos-fl

  2. Create a virtual environment and install the package in development mode:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev,test,lint]"

  3. Install pre-commit hooks:

    pre-commit install

This will set up linting, formatting, and type checking that will run automatically on commit.

Development Workflow

  1. Create a Feature Branch

    Always create a new branch for your changes:

    git checkout -b feature/your-feature-name

  2. Make Changes

    Implement your changes following our coding standards (detailed below).

  3. Run Tests

    Ensure your changes don’t break existing functionality:

    pytest

  4. Format and Lint Code

    Format your code and check for linting errors:

    isort .
black .
ruff check --fix .
mypy .

  5. Commit Changes

    Follow the Commit Guidelines when writing commit messages.

  6. Create a Pull Request

    Push your changes and create a pull request on GitHub.

Coding Standards

ICOS-FL follows the following coding standards:

Python Version

ICOS-FL supports Python 3.10 and newer. Ensure your code is compatible with these versions.

Imports

  • Use absolute imports for external packages

  • Use relative imports for internal modules

  • Group imports in the following order: 1. Standard library imports 2. Third-party imports 3. Local application imports

  • Use isort to automatically sort imports

Type Annotations

All code should include type annotations:

  • Use type annotations for all function parameters and return values

  • Use Optional for parameters that can be None

  • Use Union for parameters that can be multiple types

  • Use generic types where applicable (e.g., List[int], Dict[str, Any])

Documentation

  • All public classes, methods, and functions should have docstrings

  • Follow Google-style docstring format

  • Include type information in docstrings for better IDE support

Example:

def process_metrics(df: pd.DataFrame, columns: List[str]) -> pd.DataFrame:
    """Process metrics data.

    Args:
        df: DataFrame containing raw metrics data
        columns: List of column names to process

    Returns:
        Processed DataFrame with transformed metrics

    Raises:
        ValueError: If any column in columns is not present in df
    """

Error Handling

  • Use specific exception types rather than generic Exception

  • Handle exceptions at the appropriate level

  • Document expected exceptions in docstrings

  • Use context managers for resource management

Testing

  • Write unit tests for all new functionality

  • Use pytest fixtures for common test setup

  • Aim for high test coverage, especially for critical components

  • Include both positive and negative test cases

Commit Guidelines

We follow conventional commits for commit messages:

  • feat: A new feature

  • fix: A bug fix

  • docs: Documentation only changes

  • style: Changes that do not affect the meaning of the code

  • refactor: A code change that neither fixes a bug nor adds a feature

  • perf: A code change that improves performance

  • test: Adding missing tests or correcting existing tests

  • chore: Changes to the build process or auxiliary tools

Example commit message:

feat(client): add support for multi-step prediction

Implement recursive multi-step prediction in the LSTM model.
This allows the model to forecast further into the future by
recursively feeding predictions back into the model.

Closes #123

Pull Request Process

  1. Create a Pull Request (PR) with a clear title and description

  2. Link to any related issues using keywords like “Fixes #123” or “Relates to #456”

  3. Ensure all CI checks pass

  4. Request a review from relevant maintainers

  5. Address feedback from code review

  6. Update documentation if your changes affect user-facing features

  7. Once approved, a maintainer will merge your PR

Pull requests should be focused on a single feature or bug fix to make review easier.

Versioning

ICOS-FL follows Semantic Versioning (SemVer):

  • MAJOR version for incompatible API changes

  • MINOR version for functionality added in a backward compatible manner

  • PATCH version for backward compatible bug fixes

Version updates are handled by maintainers. Contributors should not modify version numbers.

Code of Conduct

All contributors are expected to follow our Code of Conduct. Please be respectful and considerate of others when contributing to the project.