Contributing & Development

Contributions are welcome, and they are greatly appreciated! Every little helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs to our issue page. If you are reporting a bug, please include:

  • Your operating system name and version.

  • Any details about your local setup that might be helpful in troubleshooting.

  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

Larvaworld could always use more documentation, whether as part of the official larvaworld docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is via our issue page on GitHub. If you are proposing a feature:

  • Explain in detail how it would work.

  • Keep the scope as narrow as possible, to make it easier to implement.

  • Remember that this is a volunteer-driven project, and that contributions are welcome 😊

Development Installation

If you want to modify the source code or contribute to Larvaworld, follow these steps:

1. Fork and Clone the Repository

Fork the repository on GitHub, then clone your fork locally:

git clone git@github.com:your_name_here/larvaworld.git
cd larvaworld

3. Activate the Virtual Environment

poetry shell

4. Install Pre-commit Hooks

Pre-commit hooks ensure code quality checks run automatically before each commit:

pre-commit install

This will run:

  • Code formatting (ruff, black)

  • Linting (ruff, flake8)

  • File checks (end of files, trailing whitespace)

  • Other quality checks

You can also run all checks manually:

pre-commit run --all-files

Development Workflow

1. Create a Branch

Create a branch for your changes:

git checkout -b name-of-your-bugfix-or-feature

Branch naming conventions:

  • fix/ for bug fixes

  • feat/ for new features

  • docs/ for documentation changes

  • refactor/ for code refactoring

2. Make Your Changes

Make your changes locally. Remember to:

  • Follow the existing code style

  • Add docstrings for new functions/classes

  • Update documentation if needed

  • Write tests for new features or bug fixes

3. Run Tests Locally

Before committing, ensure your changes pass all tests:

# Run all tests
poetry run pytest

# Run a specific test file
poetry run pytest tests/path/to/test_file.py

# Run tests with coverage
poetry run pytest --cov=larvaworld --cov-report=term

4. Run Linting and Formatting

Pre-commit hooks will run automatically, but you can also run them manually:

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

# Run specific checks
pre-commit run ruff --all-files
pre-commit run black --all-files

5. Commit Your Changes

Commit your changes following Conventional Commits:

git add .
git commit -m "feat(scope): your detailed description of your changes"

Commit message format:

  • type(scope): description - Recommended (scope helps categorize changes)

  • type: description - Also valid (scope is optional in Conventional Commits)

Common type values:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation changes

  • refactor: Code refactoring (no behavior change)

  • test: Test additions or changes

  • chore: Maintenance tasks (dependencies, config, etc.)

  • build: Build system or dependency changes

Common scope examples in this repo: sim, model, process, reg, screen, plot, ipc, cli, docs, ci, deps.

Examples:

  • feat(sim): add batch-run storage output

  • fix(process): normalize shapes for collision checks

  • docs: update installation instructions

  • refactor(core): remove deprecation warnings

  • chore(deps): update dependencies

The commit message will be validated by CI using commitlint. If you’ve installed pre-commit hooks, it will be checked at commit time.

6. Push and Create a Pull Request

Push your branch to GitHub:

git push origin name-of-your-bugfix-or-feature

Then create a pull request:

Via GitHub website:

  1. Go to the repository on GitHub

  2. Click “New Pull Request”

  3. Select your branch

  4. Fill in the PR description

Via GitHub CLI:

gh pr create --fill

Pull Request Process

Opening a PR

We encourage opening pull requests as early as possible, even for work in progress. Use draft pull requests if your work is still incomplete. This allows for early feedback and discussion.

PR Guidelines

  1. Include tests: Add tests for new features or bug fixes

  2. Update documentation: Update relevant documentation for significant features

  3. Follow code style: Ensure your code follows the project’s style (enforced by pre-commit)

  4. Write clear commit messages: Follow Conventional Commits format

  5. Keep PRs focused: One feature or fix per PR when possible

PR Review Process

  1. Automated checks: CI will automatically run:

    • Linting and formatting checks

    • Commit message validation

    • Full test suite on multiple platforms (Linux, macOS, Windows)

    • Code coverage reporting

  2. Review: Maintainers will review your PR. Address any feedback by:

    • Making requested changes

    • Pushing new commits to the same branch

    • Discussing any concerns in the PR comments

  3. Approval: Once approved, a maintainer will merge your PR.

Continuous Integration (CI)

Larvaworld uses GitHub Actions for continuous integration. The CI pipeline runs automatically on:

  • Push to master: Full test suite and release checks

  • Pull requests: Full test suite and linting

  • Scheduled runs: Weekly full test suite (Mondays at 3:00 UTC)

  • Manual trigger: Can be triggered manually via workflow_dispatch

CI Jobs

The CI pipeline includes:

  1. Lint: Code formatting and linting checks

    • Runs pre-commit with all hooks

    • Automatically commits formatting fixes if needed

  2. Commitlint: Validates commit messages follow Conventional Commits

  3. Full Test Suite (Ubuntu, Python 3.11):

    • Installs dependencies with Poetry

    • Runs full test suite with coverage

    • Uploads coverage to Codecov

  4. Smoke Tests (Matrix):

    • Tests on multiple platforms: Ubuntu, macOS, Windows

    • Tests on Python 3.10 and 3.11

    • Runs full test suite with coverage

Viewing CI Results

  • GitHub Actions tab: View all CI runs and their status

  • PR checks: See CI status directly in your pull request

  • Codecov: View code coverage reports and changes

Triggering Tests Manually

You can trigger CI runs manually:

  1. Go to the “Actions” tab on GitHub

  2. Select the “CI” workflow

  3. Click “Run workflow”

  4. Choose the branch and click “Run workflow”

You can also trigger tests by pushing an empty commit:

git commit --allow-empty -m "ci: trigger tests"
git push

Release Process

Releases are automated using python-semantic-release and triggered automatically when changes are merged to the master branch.

How Releases Work

  1. Version Detection: The next version is determined automatically based on commit messages:

    • feat: commits → minor version bump

    • fix: commits → patch version bump

    • BREAKING CHANGE: → major version bump

  2. Release Job: The release job runs after all CI checks pass:

    • Creates a new Git tag

    • Updates version in pyproject.toml

    • Creates a GitHub Release

    • Publishes to PyPI

  3. Release Environment: The release job requires the release environment to be configured with appropriate permissions.

Manual Release

If needed, releases can be triggered manually:

  1. Go to the “Actions” tab on GitHub

  2. Select the “CI” workflow

  3. Find the “release” job

  4. Click “Run workflow” (if available)

Or use semantic-release locally (dry run):

poetry run semantic-release version --dry-run

Documentation Build

Documentation is built automatically on ReadTheDocs when changes are pushed to master. The documentation is also built during CI for validation.

Building Documentation Locally

To build and preview documentation locally:

# Install documentation dependencies (if not already installed)
poetry install --with docs

# Build documentation
cd docs
poetry run sphinx-build -b html . _build/html

# View the documentation
# Open _build/html/index.html in your browser

Documentation Structure

  • Source files: docs/ directory

  • Configuration: docs/conf.py

  • Build output: docs/_build/

  • ReadTheDocs: Automatically builds from master branch

Documentation Guidelines

  • Use reStructuredText (.rst) or Markdown (.md) for documentation

  • Follow the existing documentation style

  • Include code examples where appropriate

  • Update the table of contents in docs/index.rst if adding new pages

Tips

Running a Subset of Tests

# Run tests in a specific directory
poetry run pytest tests/specific/directory

# Run tests matching a pattern
poetry run pytest -k "test_pattern"

# Run tests with verbose output
poetry run pytest -v

Debugging

# Run tests with debugger
poetry run pytest --pdb

# Run with print statements visible
poetry run pytest -s

Code Coverage

# Generate coverage report
poetry run pytest --cov=larvaworld --cov-report=html

# View coverage report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Getting Help

If you need help or have questions:

  • GitHub Issues: Open an issue for bugs or feature requests

  • Discussions: Use GitHub Discussions for questions

  • Email: Contact the maintainers at p.sakagiannis@uni-koeln.de