Contribute

Contributor Guide

Set up a development checkout, run the core checks for your change, and choose the smallest extension chain that matches your change.

Set Up the Repository

git clone https://github.com/md12ol/GraphEvolutionTool.git
cd GraphEvolutionTool
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip maturin
maturin develop --release

On Windows, in PowerShell: use py in place of python3, skip the activate line entirely, because a stock machine refuses to run it, and write .venv\Scripts\python.exe wherever a command on this page says python or python3. cargo and git lines are unchanged.

One exception, and it is the last line above. maturin reads the VIRTUAL_ENV variable rather than the interpreter it was started with, so the substitution alone is not enough. Set the variable yourself and no execution-policy change is needed:

$env:VIRTUAL_ENV = "$PWD\.venv"
.venv\Scripts\maturin.exe develop --release

It lasts for that PowerShell session only, so set it again in a new window. Allowing scripts once and activating properly is the alternative. See PowerShell refuses to run Activate.ps1.

You need a current stable Rust toolchain, Python 3.8 or newer, and Git. The build installs the Python module into the active virtual environment. The Rust crate is the workspace member in get/.

Run the Core Checks

cargo fmt -p graph-evolution-tool --check
cargo clippy -p graph-evolution-tool --all-targets --features cli -- -D warnings
cargo test -p graph-evolution-tool --features cli
cargo run -p graph-evolution-tool --example library_route
python tools/test_stubs.py
python tools/build_bundle.py --check
python3 documentation/check_refs.py

CI also runs every Rust example and conditional Python/tool tests; run the commands relevant to the files you changed. Run the documentation checker from the repository root. It checks source references, extension step tables, displayed function signatures, navigation membership, internal links, and anchors. The bundle check confirms that documentation/get-examples.zip and its readable HTML page still match the source files under get-examples/.

Find the Code

Area	Start in
Graph storage and edge behavior	`get/src/graph.rs` and `graph_io.rs`
Genome interface and implementations	`get/src/genomes/`
Evolution loops	`get/src/evolver/`
Objectives and epidemic simulation	`get/src/fitness.rs` and `sir.rs`
Config schema and validation	`get/src/config.rs`
Concrete route assembly	`get/src/dispatch.rs`
Python config and results	`get/src/py_config.rs`, `py_result.rs`, and `lib.rs`
Command-line route	`get/src/bin/run.rs`
Runnable examples	`examples/` and `get/examples/`

Choose the Extension Point

Begin with the Extension Map. It compares the cost and dispatch impact of every axis. Adding an objective is the supported extension path in 0.9.0:

Register a Python objective without changing GET.
Implement a Rust objective in another crate while working from source.
Add a built-in objective inside GET.

The advanced extension pages are implementation maps, not all release-ready workflows. Genome, strategy, selection, scope, replacement, crossover, and mutation pages currently carry explicit 0.9 warnings. Read the warning at the top of the relevant page before treating its steps as a supported public extension path.

Keep Interfaces in Sync

A config-visible feature usually crosses several boundaries: Rust config, validation, dispatch, Python config objects, examples, and documentation. The extension pages list these sites as numbered chains. Follow the chain for your axis instead of copying the shape of a different one.

Documentation Changes

Write what the current code does, not what a design proposes.
Add the page to NAV in documentation/assets/site.js.
Set the page's data-page path exactly.
Keep tables inside <div class="table-wrap">.
Run python3 documentation/check_refs.py, then inspect a narrow browser window.

Submit the Change

Create a focused branch.
Make the smallest coherent change and add tests that would fail without it.
Run the relevant checks above.
Open a pull request that explains the behavior change, evidence, and documentation impact.

Search the issue tracker before starting a large extension so work and design constraints are visible early.