ort/CONTRIBUTING.md

Contributing to ort

Thank you for contributing to ort =) Any contribution is welcome, whether its a huge refactor or a simple typo fix!

⚠️ AI assistance notice

This project does not allow the usage of artificial intelligence agents to write or architect code or documentation. PRs containing AI-generated or AI-assisted code/docs will be rejected. Special exception is granted to very menial tasks like filling out long match arms.

Using AI to "spruce up" issue or PR descriptions is discouraged (though machine translation is okay).

Proposing API changes & features

Please open an issue before starting any PRs that modify ort's API so that any concerns can be resolved before work begins.

Adding a new example

ort's examples are structured very differently from other Rust projects (they're really weird!). The gpt2 example is a good reference for creating new examples.

Let's call our new example agi-net. To start off, create a directory in examples/agi-net and add a Cargo.toml which looks like this:

[package]
publish = false
name = "example-agi-net"
version = "0.0.0"
edition = "2024"

[dependencies]
ort = { path = "../../" }

ort-candle = { path = "../../backends/candle", optional = true }
ort-tract = { path = "../../backends/tract", optional = true }

[features]
load-dynamic = [ "ort/load-dynamic" ]

cuda = [ "ort/cuda" ]
# ...copy the rest of the features from gpt2/Cargo.toml...
azure = [ "ort/azure" ]

backend-candle = [ "ort/alternative-backend", "dep:ort-candle" ]
backend-tract = [ "ort/alternative-backend", "dep:ort-tract" ]

[[example]]
name = "agi-net"
path = "agi-net.rs"

You can of course add dependencies and ort features as needed.

Next, examples/agi-net needs to be added to the workspace.exclude field in the root Cargo.toml to separate it from the main workspace. You can then open examples/agi-net in your IDE.

The main example examples/agi-net/agi-net.rs should look like this:

use ort::{...};

// Include common code for `ort` examples that allows using the various feature flags to enable different EPs and
// backends.
#[path = "../common/mod.rs"]
mod common;

fn main() -> ort::Result<()> {
	// Initialize tracing to receive debug messages from `ort`
	tracing_subscriber::registry()
		.with(tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| "info,ort=debug".into()))
		.with(tracing_subscriber::fmt::layer())
		.init();

	// Register EPs based on feature flags - this isn't crucial for usage and can be removed.
	common::init()?;

    ... // The AGI part is left as an exercise for the reader.

    Ok(())
}

Make sure to keep the comments annotating mod common, the tracing initialization, and common::init so their purpose is clear.

The last thing we need to do in order to make the example runnable is to add a Cargo alias to the .cargo/config.toml in the root of the repository:

[alias]
...
example-agi-net = ["run", "--manifest-path", "examples/agi-net/Cargo.toml", "--example", "agi-net", "--target-dir", "target"]

Once you're done writing the example, run it, take a screenshot of your masterpiece, and add it to examples/README.md!

Contributing code changes

After making code changes, please do the following before submitting your PR so it can be accepted quicker.

1. Format the code. This requires a nightly Rust toolchain, which can be installed with rustup toolchain install nightly. The exact version of the toolchain required can be found in .github/workflows/code-quality.yml, but it's ok if you have a newer version.

   In the root of the repository, run:

   $ cargo +nightly fmt
   

   Any warnings about "fn_call_width" can be safely ignored. I don't know how to fix that.

2. Test the code. Ideally use stable Rust for this step. When testing code, the fetch-models feature flag is required, since many tests depend on externally hosted models.

   In the root of the repository, run:

   $ cargo test --features fetch-models
   

   Generally, you don't need to enable any other features, unless you changed something related to a non-default feature like load-dynamic. Don't enable --all-features, as this will error; testing with only the default features (+ fetch-models) is fine.

   Alternative backends aren't part of the main workspace, so if you change code in one of them, you'll have to cd into that backend and run cargo test there (fetch-models is not required).

If you made changes to the public API, then make sure to update all examples as well, since they aren't in the main workspace and thus aren't checked by cargo check or cargo test.

Reporting security concerns

See SECURITY.md for information on reporting security concerns; do not use public forums to report vulnerabilities.