🛠 Ultralytics Rust Project Template

Welcome to the Ultralytics Rust Project Template! This repository provides a standardized foundation for initiating Rust projects at Ultralytics. It incorporates best practices in project structure, configuration, and essential tooling to streamline development. By using this template, Ultralytics developers can ensure consistency, maintain high quality standards, and accelerate the setup process for new Rust-based software.

🗂️ Repository Structure

This template is organized for intuitive navigation and a clear understanding of Rust project components.

• src/lib.rs: Core library code for the crate.
• src/main.rs: Example binary entrypoint that exercises the library.
• tests/: Integration tests executed with cargo test.
• docs/: Optional Markdown docs that complement Rustdoc output.
• Cargo.toml: Package metadata, dependencies, and workspace configuration.
• .gitignore: Git ignore rules tailored for Cargo builds and IDEs.
• LICENSE: Project license file (default AGPL-3.0-or-later).
• .github/workflows/: GitHub Actions for CI, formatting, and publishing the crate.

your-project/
│
├── src/                       # Library and binaries
│   ├── lib.rs
│   └── main.rs
├── tests/                     # Integration tests
│   └── basic.rs
├── docs/                      # Additional Markdown docs (optional)
│   └── README.md
├── .github/workflows/         # CI, formatting, publish pipelines
│   ├── ci.yml
│   ├── format.yml
│   └── publish.yml
├── .gitignore                 # Git ignore rules for Rust
├── Cargo.toml                 # Cargo package metadata
├── LICENSE                    # Project license file
└── README.md                  # This file

📦 Source Code Directory (src/)

The src/ directory contains both the reusable library (lib.rs) and an example binary (main.rs). Expand the library with modules as the crate grows, and keep binaries thin wrappers that delegate to library functions.

🧪 Testing Directory (tests/)

Integration tests in tests/ validate user-facing behavior. Add unit tests alongside the code they cover in src/ and run everything with cargo test.

📚 Documentation Directory (docs/)

Keep Markdown guides in docs/ for onboarding and architecture notes. Rustdoc generated from src/ remains the source of truth for API documentation (cargo doc --open).

✨ Starting a New Project

Kickstart your new Rust project using this template:

1. Create Your Repository: Click "Use this template" on GitHub to generate a new repository. Update the remote URL in your local clone.
2. Customize: Adjust Cargo.toml (package name, description, authors), refresh this README.md, and tailor .github/workflows/*.yml as needed.
3. Develop: Add modules to src/lib.rs, binaries to src/bin/ or src/main.rs, and integration tests to tests/.
4. Validate: Run cargo fmt, cargo clippy --all-targets --all-features -- -D warnings, and cargo test locally.
5. Document: Keep code-level docs up to date with /// comments and expand docs/ for guides or ADRs.

🚀 Quickstart

Install Rust via rustup and then:

cargo fmt
cargo test
cargo run

Using the published crate from another project (after release):

# Cargo.toml
[dependencies]
ultralytics-template-rust = "0.0.1"

use ultralytics_template_rust::add_numbers;

fn main() {
    let sum = add_numbers(1, 2);
    println!("Sum: {sum}");
}

🧾 Releases

• Publishes on main pushes when a new v<version> tag is needed; manual runs support dry_run: true.
• Crate name: ultralytics-template-rust; tags follow v<version> from Cargo.toml.
• Requires repository secrets: CARGO_REGISTRY_TOKEN (crates.io), GITHUB_TOKEN (built-in), and OPENAI_API_KEY for AI release notes.
• Workflow guards: fmt, clippy, tests must pass; tag/release are created only after a successful publish.

🔧 Utilizing the Template

For Ultralytics team members and external contributors:

• Clone the newly created repository based on this template to start working locally.
• Keep README.md and Cargo.toml aligned with the crate’s purpose and public API.
• Extend CI jobs if you add features like WebAssembly targets, feature-flag matrices, or documentation publishing.

With this template, Ultralytics aims to foster a culture of excellence and uniformity in Rust software development, ensuring every project starts on a solid foundation aligned with industry standards and organizational best practices.

💡 Contribute

Ultralytics thrives on community collaboration, and we deeply value your contributions! Whether it's reporting bugs, suggesting features, or submitting code changes, your involvement is crucial.

• Reporting Issues: Encounter a bug? Please report it on GitHub Issues.
• Feature Requests: Have an idea for improvement? Share it via GitHub Issues.
• Pull Requests: Want to contribute code? Please read our Contributing Guide first, then submit a Pull Request.
• Feedback: Share your thoughts and experiences by participating in our official Survey.

A heartfelt thank you 🙏 goes out to all our contributors! Your efforts help make Ultralytics tools better for everyone.

📄 License

Ultralytics offers two licensing options to accommodate diverse needs:

• AGPL-3.0 License: Ideal for students, researchers, and enthusiasts passionate about open collaboration and knowledge sharing. This OSI-approved open-source license promotes transparency and community involvement. See the LICENSE file for details.
• Enterprise License: Designed for commercial applications, this license permits the seamless integration of Ultralytics software and AI models into commercial products and services, bypassing the copyleft requirements of AGPL-3.0. For commercial use cases, please inquire about an Ultralytics Enterprise License.

📮 Contact

For bug reports or feature suggestions related to this template or other Ultralytics projects, please use GitHub Issues. For general questions, discussions, and community support, join our Discord server!