Contributing#

Thank you for your interest in contributing to SysSimX!

Development Setup#

Clone the repository:

git clone https://github.com/FlorianFrech/SystemSimulation.git
cd SystemSimulation

Create a virtual environment using conda:

conda create -n syssimx-dev python=3.12 -y
conda activate syssimx-dev

Install development dependencies:

pip install -e ".[dev]"

Install pre-commit hooks:

pre-commit install

Running Tests#

# Run all tests
pytest

# Run with coverage
pytest --cov=syssimx --cov-report=html

# Run specific test file
pytest tests/unit/core/test_base.py

# Run specific test
pytest tests/unit/core/test_base.py::TestInitialization::test_basic_init

Code Style#

We use the following tools for code quality:

Ruff - Fast Python linter and formatter
Black - Code formatting (via Ruff)
isort - Import sorting (via Ruff)
mypy - Static type checking

Run checks manually:

# Format code
ruff format .

# Check linting
ruff check .

# Type checking
mypy syssimx

Documentation Style#

We use Google-style docstrings:

def my_function(param1: float, param2: str = "default") -> bool:
    """Short description of the function.

    Longer description if needed, explaining the purpose and
    behavior in more detail.

    Args:
        param1: Description of param1.
        param2: Description of param2. Defaults to "default".

    Returns:
        Description of return value.

    Raises:
        ValueError: When param1 is negative.
        RuntimeError: When something goes wrong.

    Example:
        >>> result = my_function(1.0, "test")
        >>> print(result)
        True

    Note:
        Additional notes about usage or implementation.

    See Also:
        related_function: Does something related.
    """

Building Documentation#

python -m sphinx -b html docs docs/_build/html

Run a warning-strict build before submitting documentation changes:

python -m sphinx -b html docs docs/_build/html-check -W --keep-going

Pull Request Process#

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes
Add tests for new functionality
Ensure all tests pass: pytest
Update documentation if needed
Commit with clear messages
Push to your fork
Create a Pull Request

Commit Messages#

Use conventional commits:

feat: Add new component type
fix: Correct event detection edge case
docs: Update quickstart guide
test: Add integration tests for hybrid algorithm
refactor: Simplify port state management

Reporting Issues#

Please include:

SysSimX version: python -c "import syssimx; print(syssimx.__version__)"
Python version: python --version
Operating system
Minimal reproducible example
Expected vs actual behavior
Full error traceback if applicable

Maintainer Release Checklist#

These steps are intended for maintainers publishing a package release.

# 0) From project root
cd /home/flo/code/SystemSimulation

# 1) Ensure build/upload tools are available
python -m pip install --upgrade build twine

# 2) Build source + wheel
rm -rf dist/ build/ *.egg-info
python -m build

# 3) Validate package metadata/artifacts
python -m twine check dist/*

# 4) Upload to TestPyPI (will prompt for credentials/token)
python -m twine upload --repository testpypi dist/*
# If using token auth:
# python -m twine upload --repository testpypi -u __token__ -p "pypi-<TEST_PYPI_TOKEN>" dist/*

# 5) Install from TestPyPI (plus PyPI for dependencies)
python -m pip install --index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple \
syssimx

# 6) Verify import + installed version
python -c "import syssimx; print(syssimx.__version__)"

# 7) Optional: show resolved package details
python -m pip show syssimx
python -m pip freeze | rg syssimx

Contributing

Contents