Contribution Guidelines

June 3, 2026 · View on GitHub

It’s an honor to have you on board!

We are proud of this project and have been working to make it great since day one. We believe you will love it, and we know there’s room for improvement. We want to

  • implement features that make what you want to do possible and/or easy.
  • write more tutorials and examples that help you get familiar with Optuna.
  • make issues and pull requests on GitHub fruitful.
  • have more conversations and discussions on GitHub Discussions.

We need your help and everything about Optuna you have in your mind pushes this project forward. Join Us!

If you feel like giving a hand, here are some ways:

  • Implement a feature
    • If you have some cool idea, please open an issue first to discuss design to make your idea in a better shape.
  • Send a patch
  • Report a bug
    • If you find a bug, please report it! Your reports are important.
  • Fix/Improve documentation
    • Documentation gets outdated easily and can always be better, so feel free to fix and improve
  • Let us and the Optuna community know your ideas and thoughts.
    • Contribution to Optuna includes not only sending pull requests, but also writing down your comments on issues and pull requests by others, and joining conversations/discussions on GitHub Discussions.
    • Also, sharing how you enjoy Optuna is a huge contribution! If you write a blog, let us know about it!

Pull Request Guidelines

If you make a pull request, please follow the guidelines below:

Detailed conventions and policies to write, test, and maintain Optuna code are described in the Optuna Wiki.

Setup Optuna-Integration

git clone git@github.com:YOUR_NAME/optuna-integration.git
cd optuna-integration
uv sync

Checking the Format, Coding Style, and Type Hints

Code is formatted with black, and docstrings are formatted with blackdoc. Coding style is checked with flake8 and isort, and additional conventions are described in the Wiki. Type hints, PEP484, are checked with mypy.

$ uv sync --group checking
# black and isort format
$ uv run black .
$ uv run isort .

# flake8 type checking
$ uv run flake8 tests optuna_integration

# mypy type checking
$ uv run mypy tests optuna_integration

You can use pre-commit to automatically check the format, coding style, and type hints before committing. The following commands automatically fix format errors by auto-formatters.

$ uv sync --group checking
$ uv run pre-commit install
$ uv run pre-commit run --all-files

Documentation

When adding a new feature to the framework, you also need to document it in the reference.

The Optuna-Integration document is still in the Optuna document, if you want to add to it, please see the documentation section of the Optuna repository.

Unit Tests

When adding a new feature or fixing a bug, you also need to write sufficient test code. We use pytest as the testing framework and unit tests are stored under the tests directory.

Please install some required packages at first.

# Install required packages to test.
uv sync --group test

# Install required packages on which each integration module depends.
uv sync --group test --extra "${INTEGRATION_MODULE_NAME}"

# For example, for optuna_integration/lightgbm,
uv sync --group test --extra lightgbm

You can run your tests as follows:

# Run all the unit tests.
uv run pytest

# Run all the unit tests defined in the specified test file.
uv run pytest tests/${TARGET_TEST_FILE_NAME}

# Run the unit test function with the specified name defined in the specified test file.
uv run pytest tests/${TARGET_TEST_FILE_NAME} -k ${TARGET_TEST_FUNCTION_NAME}

See also the Optuna Test Policy, which describes the principles to write and maintain Optuna tests to meet certain quality requirements.

Continuous Integration and Local Verification

Optuna-Integration repository uses GitHub Actions.

Creating a Pull Request

When you are ready to create a pull request, please try to keep the following in mind.

First, the title of your pull request should:

  • briefly describe and reflect the changes
  • wrap any code with backticks
  • not end with a period

The title will be directly visible in the release notes.

For example:

  • Support multi-objective optimization in MLflowCallback.

Second, the description of your pull request should:

  • describe the motivation
  • describe the changes
  • if still work-in-progress, describe remaining tasks