CI/CD Workflows

FUSION uses GitHub Actions for continuous integration and deployment. This page explains what each workflow does and what checks your code must pass.

Overview

When you push code or open a PR, several automated workflows run:

Workflow

Purpose

Unit Tests

Runs pytest on all unit tests

Code Quality

Linting, formatting, type checking, security

Commit Message Validation

Ensures conventional commit format

Cross-Platform Tests

Tests on Windows, macOS, and Linux

Algorithm Results Verification

Verifies algorithm consistency

Documentation

Builds and deploys Sphinx docs

Workflow files are located in .github/workflows/.

Unit Tests

File: unittests.yml

Runs on PRs and pushes to develop, main, and release/** branches.

What it checks:

  • All pytest tests pass

  • Tests run on Python 3.11

If it fails: Fix the failing tests before your PR can be merged.

Code Quality

File: quality.yml

Runs on every push and PR.

What it checks:

  • Format check: Code follows ruff formatting rules

  • Linting: No linting errors (ruff)

  • Type checking: mypy type annotations are correct

  • Security: No vulnerabilities detected (bandit)

  • Dead code: No unused code (vulture)

  • Test coverage: Pytest with coverage reporting

If it fails: Run these commands locally to fix issues:

make format      # Auto-fix formatting
make lint        # Check for linting issues
make test        # Run tests

Commit Message Validation

File: commit_message.yml

Validates that commit messages follow the conventional commits format.

What it checks:

  • Message follows type(scope): description format

  • Subject line is under 100 characters

  • Description is at least 5 characters

  • No trailing period

Valid types: feat, fix, docs, style, refactor, perf, test, chore, build, ci

If it fails: Amend your commit message:

git commit --amend -m "feat(module): proper commit message"
git push --force-with-lease

See Commit Messages for detailed guidelines.

Cross-Platform Tests

File: cross_platform.yml

Ensures FUSION works on all supported operating systems.

What it checks:

  • Installation succeeds on Windows, macOS, and Linux

  • Basic simulation runs successfully on all platforms

If it fails: Your changes may have platform-specific issues. Check the logs to see which platform failed.

Algorithm Results Verification

File: algorithm_verification.yml

Compares algorithm results before and after changes to ensure consistency across many algorithms.

What it checks:

  • Algorithm outputs match expected baselines

  • Results remain consistent after code changes

  • No regressions in algorithm behavior

If it fails: Your changes may have altered algorithm behavior. This could be intentional (update baselines) or a bug (fix your code).

Documentation

File: docs.yml

Builds and deploys the Sphinx documentation.

What it checks:

  • Documentation builds without errors

  • No broken links (on PRs)

  • No spelling errors (on PRs)

Deployment: When changes are merged to main, documentation is automatically deployed to GitHub Pages.

If it fails: Check the Sphinx build output for errors. Common issues:

  • Invalid RST/Markdown syntax

  • Missing files referenced in toctree

  • Broken cross-references

Checking Workflow Status

You can see workflow status:

  1. On your PR: Check marks or X marks appear next to each workflow

  2. Actions tab: Go to https://github.com/SDNNetSim/FUSION/actions

  3. Commit status: Each commit shows workflow results

Running Checks Locally

Before pushing, run checks locally to catch issues early:

# Run all quality checks
make check-all

# Or run individual checks
make format      # Format code
make lint        # Lint code
make test        # Run tests

Pre-commit hooks also run automatically when you commit.