Contributing

Contributing#

How to contribute to Kiso the project.

This page covers contributing to Kiso itself (bug reports, features, code). For extending Kiso with new plugins, see How Kiso extensions work.

Reporting bugs#

File bug reports on GitHub Issues.

A good bug report includes:

  • Kiso version (kiso version)

  • Python version (python --version)

  • Operating system

  • The experiment config file (or a minimal reproduction)

  • The full error output (run with kiso --debug for verbose output)

  • What you expected to happen vs what actually happened

Proposing features#

Open a GitHub Issue with the label enhancement. Describe:

  • The use case you are trying to address

  • Your proposed solution (optional, but helpful)

  • Alternatives you considered

Large or breaking changes should be discussed in an issue before submitting a PR.

Development setup#

# Clone the repo
git clone https://github.com/pegasus-isi/kiso.git
cd kiso

# Install in development mode with all dependencies
pip install -e ".[all]"

# Install pre-commit hooks
pre-commit install

Running the test suite#

# Full test suite with coverage (recommended)
tox -e py311

# Direct pytest
pytest --cov=src --no-cov-on-fail tests/

# Single test file
pytest tests/test__main__.py

# Single test function
pytest tests/test__main__.py::test_check

All tests must pass before submitting a PR.

Code style#

Tool

Purpose

ruff

Linter and formatter (black-compatible, line length 88)

mypy

Type checking

pre-commit

Runs all checks automatically on commit

Run all checks manually:

pre-commit run --all-files

Run individual tools:

# Lint and format
ruff check --fix src/ tests/
ruff format src/ tests/

# Type check
mypy src/

Code style conventions:

  • Google-style docstrings

  • Type annotations required for all public functions and methods

  • No print() — use logging instead

Commit conventions#

Commits must follow Conventional Commits. The pre-commit hook (commitizen) enforces this.

Common types: feat, fix, docs, refactor, test, perf, build, chore.

Examples:

feat(fabric): add floating IP support
fix(htcondor): correctly configure IPv6 trust domain
docs: add multi-testbed tutorial

Pull request process#

  1. Fork the repository and create a branch from main

  2. Make your changes with tests

  3. Ensure pre-commit run --all-files and tox -e py311 pass

  4. Submit a PR against main

  5. A maintainer will review and either approve, request changes, or close with explanation

PRs should be focused — one feature or bug fix per PR. Do not mix unrelated changes.

How decisions are made#

Kiso is developed at USC Information Sciences Institute. Maintainers review and merge PRs. For significant design decisions, open a GitHub Issue first to discuss before investing time in an implementation.

See also#