mirror of
https://github.com/pykeio/ort
synced 2026-04-25 16:34:55 +02:00
120 lines
5.0 KiB
Markdown
120 lines
5.0 KiB
Markdown
# 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](https://github.com/pykeio/ort/blob/d931f0ac509ec075cdc81f3c4872c09b7122d752/src/tensor/types.rs#L109-L166).
|
|
|
|
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:
|
|
```toml
|
|
[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:
|
|
```rs
|
|
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:
|
|
```toml
|
|
[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.
|
|
|
|
<ol>
|
|
<li>
|
|
|
|
**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`](https://github.com/pykeio/ort/blob/main/.github/workflows/code-quality.yml), but it's ok if you have a newer version.
|
|
|
|
In the root of the repository, run:
|
|
```shell
|
|
$ cargo +nightly fmt
|
|
```
|
|
|
|
Any warnings about "`fn_call_width`" can be safely ignored. I don't know how to fix that.
|
|
|
|
</li>
|
|
<li>
|
|
|
|
**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:
|
|
```shell
|
|
$ 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).
|
|
|
|
</li>
|
|
</ol>
|
|
|
|
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`](https://github.com/pykeio/ort/blob/main/SECURITY.md) for information on reporting security concerns; do not use public forums to report vulnerabilities.
|