Contributing to Minion

Minion is developed on GitHub at https://github.com/khoirulmuzakka/Minion. Contributions are welcome for bug fixes, new features, tests, examples, and documentation improvements.

How to Contribute

  1. Fork the repository on GitHub.

  2. Clone your fork locally:

    git clone https://github.com/yourname/Minion.git
cd Minion

  3. Add the main repository as an upstream remote:

    git remote add upstream https://github.com/khoirulmuzakka/Minion.git

  4. Create a feature branch for your work:

    git checkout -b feature-short-description

  5. Make your changes.

  6. Run the relevant build or validation steps locally.

  7. Commit with a clear message and push your branch.

  8. Open a pull request on GitHub describing the change and any testing you performed.

Development Setup

For source builds, the main requirements are:

  • CMake 3.18 or newer

  • A C++17 compiler

  • Eigen3, or allow CMake to fetch dependencies as configured by the project

  • Python 3 and pybind11 if you are working on the Python bindings

To build from source, use the helper scripts in the repository root:

  • Windows: compile.bat

  • Linux/macOS: compile.sh

These scripts are the recommended starting point for local development because they configure the project consistently with the expected native build layout. For more detailed source-build and installation instructions, see the installation guide.

Running Tests Locally

Before opening a pull request, run the local checks relevant to the part of the project you changed.

C++ integration test

The repository includes a native integration test target in tests/test_minion.cpp. To build and run it manually with CMake:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DMINION_BUILD_BENCHMARK=ON -DMINION_BUILD_EXAMPLES=ON -DMINION_BUILD_PYTHON=ON -DMINION_BUILD_TESTS=ON
cmake --build build --target minion_test --config Release

Run the test binary directly if you want to see the numbered checks and full per-algorithm benchmark output:

build/bin/minion_test.exe

On Linux and macOS, run:

./build/bin/minion_test

Alternatively, you can run the same test through ctest:

ctest --test-dir build --output-on-failure -C Release

Note that ctest does not show the detailed output for passing tests by default; it mainly prints a short summary unless the test fails.

This test checks that:

  • the core C++ algorithms run successfully on benchmark problems

  • the returned objective values are finite

  • the evaluation counts stay within the configured maxevals budget (with a small slack)

  • the Sphere and Rosenbrock runs satisfy simple solution-quality thresholds

  • representative CEC2017 benchmark cases run without non-finite values or budget overruns

  • native C++ callback early stopping returns CallbackStopped

  • C++ stream output for TerminationStatus and MinionResult is readable

The benchmark sections are mainly integration and stability checks rather than strict performance benchmarks. They intentionally use simple thresholds so that the tests catch regressions without becoming sensitive to small stochastic differences.

Python binding test

The repository also includes tests/test_minionpy.py for the public Python API. Run it from the repository root after building or installing minionpy. See the installation guide if you need the source-build or install steps.

python tests/test_minionpy.py

This script uses a small numbered runner and prints output in the form Test i/N: check name: passed, followed by N/N Passed.. It exercises the Python wrapper, pybind callback path, enum exposure, and the C++ optimizers through the public minionpy interface.

The Python test verifies that:

  • TerminationStatus prints as readable strings

  • MinionResult exposes readable status values

  • callbacks receive a Python MinionResult

  • callbacks returning True stop optimization with CallbackStopped

  • callbacks returning False or None continue optimization

  • every algorithm exposed by minionpy.Minimizer returns a terminal finite result rather than Running or RuntimeError

  • every algorithm exposed by minionpy.Minimizer honors callback early stopping

  • algorithms that do not support tolerance stopping, such as ARRDE and j2020, report budget exhaustion instead of fake convergence

  • restart-based CMA-ES variants expose restart-cap behavior without pretending budget exhaustion is convergence

  • Dual_Annealing callback stopping works both with and without local search

  • L_BFGS and L_BFGS_B callback stopping works

  • vectorized helper functions return finite outputs

  • the CEC2017Functions wrapper evaluates batched inputs correctly

  • direct and generic RDEX wrappers run successfully

If your change only affects documentation, you do not need to run the full optimization tests, but you should still verify that the docs build locally if you changed reStructuredText, notebooks, or generated API content.

CI Coverage

GitHub Actions runs the main validation workflow from .github/workflows/ci.yml.

At the time of writing, CI covers:

  • C++ integration tests through minion_test and ctest

  • Python package and extension build checks

  • Python runtime validation through tests/test_minionpy.py

  • packaging jobs for release artifacts

In practice, the main CI workflow builds both the native C++ integration test and the Python extension, runs the C++ test through ctest, and then runs the Python API validation script.

If your change affects the Python bindings, examples, packaging, or documentation, verify those areas directly instead of assuming the C++ build alone is enough.

What to Check Before Submitting

  • The project still builds successfully.

  • New or changed behavior is covered by tests or examples when practical.

  • Documentation is updated when user-facing behavior changes.

  • Code follows the existing style and naming conventions in the surrounding files.

Reporting Bugs and Requesting Features

Use the GitHub issue tracker:

https://github.com/khoirulmuzakka/Minion/issues

When opening an issue, include:

  • A clear description of the problem or request

  • Steps to reproduce the issue, if applicable

  • The platform, compiler, Python version, or package version when relevant

  • Any error messages, logs, or screenshots that help narrow down the cause

Documentation Contributions

The documentation is written in reStructuredText under docs/source/ and built with Sphinx. Doxygen output is also used by the docs build.

If your environment already has the required documentation dependencies installed, you can build the docs locally from the docs directory:

make html

On environments where the helper scripts are used, documentation generation may also be handled as part of the project build when the required tools are available.

Pull Request Notes

  • Keep pull requests focused on a single change when possible.

  • Explain the motivation for the change, not just the code diff.

  • Link related issues if there are any.

  • Call out any behavior changes that may affect existing users.

Thank you for contributing to Minion.