Contributing

All contributions are welcome: bug reports, documentation fixes, tests, and code. Everything happens on GitHub.

🔗Reporting bugs

If you hit a bug, unexpected behavior, or an inconsistency, open an issue. Many problems are found by users first, and a report helps everyone.

A useful report includes:

• A clear description of the problem
• Steps to reproduce it
• Expected and actual behavior
• Relevant error messages or logs
• A minimal reproducible example, when possible

🔗Improving documentation

If part of this guide is confusing, incomplete, outdated, or hard to follow, say so. Getting stuck while trying to do something in oximo usually means the docs can be better, not that you missed something.

Worth sending:

• Clarifications to existing guides
• More examples
• Tutorials
• Better API explanations
• Typo and formatting fixes

Open an issue or send a pull request directly.

🔗Contributing code

Bug fixes, performance work, new features, tests, and refactors are all fair game.

1. Fork the repository
2. Create a branch for your changes
3. Make your modifications
4. Add or update tests when appropriate
5. Run cargo fmt and make sure cargo clippy passes
6. Write a commit message following the naming convention
7. Run the tests relevant to your change
8. Open a pull request

Keep pull requests focused and reasonably scoped. Smaller ones are easier to review and land.

🔗Testing

Some tests need third-party tools, including commercial solvers. Default features don't depend on any of them.

You are not expected to run tests for crates unrelated to your change. Skip them with --exclude:

cargo test --workspace --exclude oximo-gurobi

A reviewer runs the full suite manually before merging. The GitHub CI workflow can't execute all tests because of solver licensing restrictions.

🔗Commit naming convention

oximo follows a commit naming convention that keeps the history readable and makes the scope of a change obvious at a glance.

Scope	Prefix
A single crate	oximo-<crate-name>:
Workspace configuration	workspace:
GitHub workflows or repo config	github:
More than one backend	backends:

Examples:

oximo-core: Improve error handling
workspace: Update dependency versions
github: Add CI workflow for testing
backends: Improve mapping of terminations

🔗AI-assisted contributions

AI-assisted contributions are allowed. Contributors remain fully responsible for the quality, correctness, licensing, and usefulness of what they submit. The standards are the same either way.

🔗Accountability

Review and validate AI-assisted content before submitting it. Using an AI tool does not transfer responsibility for correctness, code quality, license compliance, security, or documentation accuracy.

🔗Transparency

Disclose it when a significant portion of a contribution is generated by, or copied verbatim from, an AI tool. Routine help (grammar, spelling, minor phrasing) needs no disclosure.

Note it in the pull request description, or use a commit trailer:

Assisted-by: generic LLM chatbot

This helps the project evaluate tooling practices and refine these guidelines over time.

🔗Licensing

By contributing to oximo you agree that your contributions are licensed under the same dual-license terms as the project:

• MIT License
• Apache License 2.0

Unless stated otherwise, all submitted contributions are assumed to be provided under both.