Skip to main content
All types of contributions are encouraged and valued. This guide will help you get started with contributing to Chainbench and ensure a smooth experience for everyone involved.

​
Ways to Support the Project

If you like the project but don’t have time to contribute code, there are other ways to show your support:
  • Star the project on GitHub
  • Tweet about it and share with your network
  • Reference Chainbench in your project’s readme
  • Mention the project at local meetups and tell your friends/colleagues

​
Getting Started

1

Install Dependencies

Chainbench uses Poetry for dependency management:
poetry install
2

Set Up Pre-commit Hooks

Install pre-commit hooks to automatically check code quality:
poetry run pre-commit install
3

Make Your Changes

Follow the coding conventions and test your changes thoroughly.
4

Run Quality Checks

Before submitting, ensure all checks pass:
poetry run pre-commit run --all-files

​
Coding Conventions

Chainbench follows strict code quality standards to maintain consistency:
  • Black: 120-character line length for code formatting
  • isort: Black-compatible profile for import sorting
  • Type hints: Use type hints where appropriate
  • All code must pass MyPy type checking
  • Flake8: Standard linting with E203 and W503 ignored for Black compatibility
  • Keep the codebase clean and well-documented
  • Follow existing patterns in the codebase

​
Code Quality Checks

Before completing any task, run these quality checks:
CommandPurpose
poetry run black .Format code to project standards
poetry run isort .Sort imports
poetry run flake8Run linting checks
poetry run mypy .Run type checks
Or use pre-commit hooks to run all checks at once: 
poetry run pre-commit run --all-files

​
Testing Guidelines

Always use headless mode with short test durations during development. Never run long-duration tests during development sessions.
Test your changes progressively:
1

Unit Testing

Test individual user classes and methods in isolation.
2

Profile Validation

Verify profiles load correctly:
poetry run chainbench list profiles
3

Short Headless Tests

Run brief tests with minimal load:
poetry run chainbench start --profile evm.light --users 5 --workers 1 --test-time 30s --target https://test-node --headless --autoquit
4

Method Discovery

Test endpoint compatibility:
poetry run chainbench discover https://test-node --clients geth

​
Testing Best Practices

  • Start with minimal load: Use few users and low spawn rates
  • Use —autoquit flag: Ensures tests terminate properly
  • Test against dev nodes first: Never test production nodes during development
  • Start with light profiles: Before testing heavy profiles
  • Monitor target node health: During benchmarks

​
Development Workflow

1

Make Changes

Implement your feature or bug fix in the source code.
2

Format Code

Run formatting tools:
poetry run black . && poetry run isort .
3

Run Linting

Check for linting issues:
poetry run flake8
4

Type Checking

Verify type annotations:
poetry run mypy .
5

Test with Minimal Profile

Validate changes with a simple test:
poetry run chainbench start --profile evm.light --users 5 --workers 1 --test-time 30s --target https://test-node --headless --autoquit
6

Gradually Increase Complexity

Test with more complex scenarios and higher load.

​
Managing Dependencies

If you need to add or update dependencies:
1

Add Dependency

Use Poetry to manage dependencies:
poetry add <package>
# or for dev dependencies
poetry add --group dev <package>
2

Update Lock File

Update the lock file without updating other dependencies:
poetry lock --no-update
3

Install Updated Dependencies

Install the newly added dependencies:
poetry install
4

Verify Compatibility

Ensure compatibility with Python 3.10+ as specified in the project.

​
Reporting Bugs

​
Before Submitting a Bug Report

  • Ensure you’re using the latest version
  • Verify it’s actually a bug and not an error on your side
  • Check if there’s already a bug report for your issue
  • Search the internet to see if others have encountered the same issue
  • Collect information about the bug:
    • Stack trace (Traceback)
    • OS, Platform, and Version
    • Python version and package versions
    • Your input and the output
    • Can you reliably reproduce the issue?

​
How to Submit a Good Bug Report

Never report security-related issues publicly. Contact the maintainers directly for security vulnerabilities.
When submitting a bug report:
  • Open an Issue on GitHub
  • Explain the expected behavior vs. actual behavior
  • Provide as much context as possible
  • Describe the reproduction steps in detail
  • Include the information you collected
The project team will:
  • Label the issue accordingly
  • Try to reproduce the issue with your steps
  • Mark it as needs-repro if steps are unclear
  • Mark it as needs-fix once reproduced

​
Suggesting Enhancements

​
Before Submitting an Enhancement

  • Ensure you’re using the latest version
  • Check if the enhancement has already been suggested
  • Verify your idea fits with the project’s scope and aims
  • Make a strong case for why this feature would benefit most users

​
How to Submit a Good Enhancement Suggestion

Enhancement suggestions are tracked as GitHub issues:
  • Use a clear and descriptive title
  • Provide a step-by-step description in detail
  • Describe the current behavior and expected behavior
  • Explain why this enhancement would be useful to most users
  • Point to other projects that implement similar features
When contributing to this project, you must agree that:
  • You have authored 100% of the content
  • You have the necessary rights to the content
  • The content you contribute may be provided under the project license

​
Questions?

Before asking a question:
  • Search for existing Issues that might help you
  • Search the internet for answers first
If you still need clarification:
  • Open an Issue on GitHub
  • Provide as much context as possible
  • Include relevant project and platform versions
We’ll take care of your issue as soon as possible.

Build docs developers (and LLMs) love

Get started for freeTalk to us