Contributing

Getting Started

Thank you for your interest in contributing to angr Management! This guide will help you get started with contributing code, tests, and documentation.

Set up your development environment

Follow the Development Setup guide to install angr Management from source with all development dependencies.

git clone https://github.com/angr/angr-management.git
cd angr-management
uv sync --all-groups

Clone the test binaries

Many tests require binary files from the angr binaries repository:

cd ..
git clone https://github.com/angr/binaries.git

The tests expect the binaries repository to be in ../binaries/ relative to the angr-management directory.

Create a branch for your changes

git checkout -b my-feature-branch

Code Style

angr Management follows strict code style guidelines enforced by Ruff.

Linting and Formatting

# Check for style issues
ruff check .

# Automatically fix issues
ruff check --fix .

# Format code
ruff format .

Style Guidelines

# ALL Python files must include this import
from __future__ import annotations

Configuration

Ruff configuration is in pyproject.toml:106-138:

Target version: Python 3.10
Line length: 120
Excluded: angrmanagement/vendor/

Testing

angr Management uses pytest for testing. All contributions should include appropriate tests.

Running Tests

All Tests
Specific Tests
Parallel Testing

# Run the full test suite
pytest

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

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

# Run a specific test file
pytest tests/test_disassembly_view.py

# Run a specific test function
pytest tests/test_main_window.py::TestMainWindow::test_load_binary

# Run tests matching a pattern
pytest -k "disassembly"

# Run tests in parallel using pytest-xdist
pytest -n auto

# Run with specific number of workers
pytest -n 4

Writing Tests

angr Management provides test base classes to simplify test creation. See tests/common.py:33-71.

from __future__ import annotations

import unittest
from tests.common import AngrManagementTestCase

class TestMyFeature(AngrManagementTestCase):
    """Test cases that need the main window."""

    def test_something(self):
        # self.main is the MainWindow instance
        workspace = self.main.workspace
        instance = workspace.main_instance

        # Your test code here
        self.assertIsNotNone(workspace)

Test Base Classes

AngrManagementTestCase (tests/common.py:33)

Creates a MainWindow instance with show=False
Provides self.main - the MainWindow
Cleans up after each test

ProjectOpenTestCase (tests/common.py:49)

Extends AngrManagementTestCase
Loads a default test binary (x86_64 true)
Provides convenience properties:
- self.workspace - The Workspace
- self.instance - The Instance
- self.project - The angr.Project
Waits for jobs to complete after setup

Headless Testing

Tests run in headless mode using Qt’s minimal platform:

# Set in CI environment (see .github/workflows/coverage.yml:16)
export QT_QPA_PLATFORM=minimal:enable_fonts

pytest

Coverage

Coverage configuration is in pyproject.toml:149-161:

# Run with coverage
pytest --cov=angrmanagement --cov-report=term-missing

# Generate HTML report
pytest --cov=angrmanagement --cov-report=html

Current coverage:

Type Checking

Run mypy to check type hints:

mypy angrmanagement tests

Configuration in pyproject.toml:140-147:

Packages checked: angrmanagement, tests
Excludes: angrmanagement/vendor/, /build, /dist

Pull Request Process

Make your changes

Write code following the style guidelines
Add tests for new functionality
Update documentation if needed
Run linting and tests locally

ruff check --fix .
ruff format .
pytest

Commit your changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add feature: description of what changed and why"

Push and create a pull request

git push origin my-feature-branch

Then create a pull request on GitHub with:

Clear title describing the change
Description of what changed and why
Any relevant issue numbers (e.g., “Fixes #123”)
Screenshots for UI changes

Respond to review feedback

Address reviewer comments
Push additional commits
Re-request review when ready

Testing Pull Requests

The CI system runs multiple test suites:

Platform Tests

Tests run on:

Windows (windows-2022)
macOS (macos-15)
Ubuntu ARM (ubuntu-24.04-arm)
Ubuntu x64 (ubuntu-latest with coverage)

See .github/workflows/ci.yml and .github/workflows/coverage.yml.

Test Groups

Unit tests - Component-level tests
Integration tests - Full workflow tests
UI tests - Interactive component tests

API Stability

The angr Management API is highly in-flux and may change between versions.If you’re building something that depends on a specific API:

Contribute a test case for that API
This helps ensure the API doesn’t break in future versions
Ask in the angr Discord if you have questions

Plugin Development

Plugins are a great way to extend angr Management without modifying core code.

Plugin Structure

Plugins are Python files containing a BasePlugin subclass:

from __future__ import annotations

from angrmanagement.plugins import BasePlugin

class MyPlugin(BasePlugin):
    def __init__(self, workspace):
        super().__init__(workspace)

    def teardown(self):
        pass

    # Override methods from BasePlugin
    # See: angrmanagement/plugins/base_plugin.py

Plugin Locations

Plugins are loaded from:

angrmanagement/plugins/ - Built-in plugins
~/.local/share/angr-management/plugins/ - User plugins

Plugin Resources

Plugin base class source
Any method or attribute can be overridden and will be called on relevant events
See existing plugins in angrmanagement/plugins/ for examples

Documentation

Documentation contributions are always welcome!

Building Documentation

# Install documentation dependencies
uv sync --group docs

# Build docs
cd docs
make html

# View docs
open _build/html/index.html

Documentation Structure

Sphinx RST - Legacy documentation in docs/
Mintlify MDX - New documentation (this site)

When adding new features, update both if applicable.

Getting Help

angr Discord

Join the community and ask questions

GitHub Issues

Report bugs or request features

Architecture Guide

Understand the codebase structure

Development Setup

Set up your development environment

Common Contribution Types

Bug Fixes

Create an issue describing the bug (if one doesn’t exist)
Write a test that reproduces the bug
Fix the bug
Verify the test passes
Submit a PR referencing the issue

New Features

Discuss the feature in an issue or on Discord first
Design the feature to fit the existing architecture
Implement the feature with comprehensive tests
Update documentation
Submit a PR with screenshots/examples

UI Improvements

Describe the UX issue or improvement
Provide mockups or examples if possible
Implement using Qt/PySide6 following existing patterns
Test on multiple platforms if possible
Include before/after screenshots in PR

Performance Improvements

Profile and identify the bottleneck
Write a benchmark test
Implement the optimization
Verify the benchmark shows improvement
Ensure existing tests still pass

Code Review Guidelines

When reviewing or submitting code:

Functionality - Does it work as intended?
Tests - Are there adequate tests?
Style - Does it follow the code style?
Performance - Are there any performance concerns?
Documentation - Is it documented appropriately?
Maintainability - Is it easy to understand and maintain?

License

By contributing to angr Management, you agree that your contributions will be licensed under the BSD-2-Clause License.

Recognition

Contributors are recognized in:

Git commit history
GitHub contributors page
Release notes (for significant contributions)

Thank you for contributing to angr Management!

Overview

Plugin Development

UI Development

Advanced

Getting Started

Code Style

Linting and Formatting

Style Guidelines

Configuration

Testing

Running Tests

Writing Tests

Test Base Classes

Headless Testing

Coverage

Type Checking

Pull Request Process

Testing Pull Requests

Platform Tests

Test Groups

API Stability

Plugin Development

Plugin Structure

Plugin Locations

Plugin Resources

Documentation

Building Documentation

Documentation Structure

Getting Help

angr Discord

GitHub Issues

Architecture Guide

Development Setup

Common Contribution Types

Code Review Guidelines

License

Recognition

Build docs developers (and LLMs) love

Overview

Plugin Development

UI Development

Advanced

​Getting Started

​Code Style

​Linting and Formatting

​Style Guidelines

​Configuration

​Testing

​Running Tests

​Writing Tests

​Test Base Classes

​Headless Testing

​Coverage

​Type Checking

​Pull Request Process

​Testing Pull Requests

​Platform Tests

​Test Groups

​API Stability

​Plugin Development

​Plugin Structure

​Plugin Locations

​Plugin Resources

​Documentation

​Building Documentation

​Documentation Structure

​Getting Help

angr Discord

GitHub Issues

Architecture Guide

Development Setup

​Common Contribution Types

​Code Review Guidelines

​License

​Recognition

Build docs developers (and LLMs) love

Getting Started

Code Style

Linting and Formatting

Style Guidelines

Configuration

Testing

Running Tests

Writing Tests

Test Base Classes

Headless Testing

Coverage

Type Checking

Pull Request Process

Testing Pull Requests

Platform Tests

Test Groups

API Stability

Plugin Development

Plugin Structure

Plugin Locations

Plugin Resources

Documentation

Building Documentation

Documentation Structure

Getting Help

Common Contribution Types

Code Review Guidelines

License

Recognition