Guidelines

OpenMHS sits between software that can be wrong and machines that can be damaged. These guidelines summarise the project's CONTRIBUTING.md, SECURITY.md and GOVERNANCE.md; those files are the authoritative versions.

The most useful contribution

Want to connect a new device? Build an adapter. Start with the adapter guide, run openmhs adapter new <name> (or openmhs profile new <protocol> for Modbus, MQTT, SCPI or HTTP), make the conformance suite pass, and list it in the adapter registry. Small, focused changes are the easiest to review.

Ground rules

1. Safety claims need evidence. Do not write that something is safe, certified or validated unless a test or report in the repository shows it. Simulated is not physical; say which one you tested.
2. No real hardware in CI or tests. Tests run against simulators and in-process fixtures. Anything that could move or power a real device must be opt-in and say so loudly.
3. Do not weaken security tests to make a change pass. If a test is wrong, say why in the pull request.
4. Be honest about scope. OpenMHS is independent and unaffiliated with Anthropic. Do not claim compatibility with the Model Hardware Standard.
5. The specification is the source of truth. If you change a schema or a spec, change the examples in spec/examples/ too.
6. Dependencies need a reason, a licence that deny.toml allows, and should be at least two weeks old. Prefer not adding one.
7. Do not hand-write cryptography. The workspace also forbids unsafe Rust.

Principles that do not change lightly

From the governance document. Changing one needs an RFC, and the bar is high.

• Deterministic policy decides what an agent may do; a model never does.
• Hardware safety systems keep final authority. OpenMHS is not a safety function.
• Claims need evidence. Simulated is never reported as physically validated.
• The project stays independent and does not claim compatibility with standards whose specifications are not public.
• Minimal dependencies; no hand-written cryptography.

Setting up

git clone https://github.com/KNambiarDJsc/Open-MHS
cd Open-MHS
git config user.email "you@example.com"     # the email on your GitHub account, so commits are credited to you
git switch -c your-branch-name              # never commit straight to main
cargo build -p openmhs-cli
cargo run -p openmhs-cli --bin openmhs -- demo

You need Rust 1.89 or newer, and Python 3.10+ for the Python SDK, the schema check and some examples. On Windows, see the install notes.

Checks before a pull request

Run what CI runs (on Windows, macOS and Linux, warnings as errors):

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo deny check                                # https://github.com/EmbarkStudios/cargo-deny
python tools/check_schemas.py                   # pip install jsonschema
(cd python/tests && PYTHONPATH=.. python -m unittest discover -s . -v)
python tools/check_registry.py                  # adapter registry
python tools/gen_matrix.py --check              # compatibility matrix is current

• Add or update tests for behaviour you change. Prefer a test that fails without your change.
• Update the documentation next to the code (docs/, spec/).

Larger changes: RFCs

For changes to the specification, the adapter contract, the API or the safety model, open an RFC first: copy docs/rfcs/0000-template.md and open a pull request with it. Decisions that stick become an ADR in docs/adr/.

Commits and pull requests

• One logical change per pull request. Explain what changed and why; link the issue.
• Commit messages: a short imperative subject, then a body when the reason is not obvious.
• Say plainly what you did not test, for example "not run on macOS".
• Use the issue and pull-request templates in the repository.

Good first issues

Small, testable without hardware, and away from the safety model. Ask on the issue before you start so work is not duplicated. From docs/good-first-issues.md:

How decisions are made

• Everyday changes: a pull request, review, merge when CI is green and the change fits the project.
• Specification, adapter contract, API, security model: an RFC first, discussed in public; lasting decisions are recorded as an ADR.
• Roles: the maintainer merges changes, cuts releases and has the last word on scope and the safety model. Contributors open issues, pull requests, adapters and RFCs. Adapter maintainers are responsible for their registry entries.

Using AI coding assistants

Our advice, not a project rule. AI assistants make it easy to produce code you have not understood, and in this project that is risky.

• You own every line you submit. Read it and be able to explain it in review.
• Give the assistant the rules. Point it at the relevant spec file, decision record and the ground rules above.
• Watch for loosened checks. The most common bad suggestion is making a failing test pass by weakening the code or the test.
• Run the checks yourself and read the output.
• Never let an assistant run commands against real equipment.

Trying real hardware

• Read docs/hardware first. Those guides have not been verified on real devices.
• Try every profile with --profile-sim before --profile.
• Start with something harmless, such as a single LED.
• Keep the device's own physical stop within reach, and know how to cut power.
• Set ranges in the profile tighter than the device's real limits.
• Grant agents read access first. Use --max-side-effect reversible, and require_approval for anything that moves or heats.
• Do not run the conformance suite against equipment in use; it sends real commands and injects faults.
• Keep MQTT and HTTP on TLS. Plaintext beyond loopback is refused unless you set allow_plaintext; only do that on an isolated test network.

Reporting security problems

Do not open a public issue for a vulnerability. On the repository, open the Security tab and choose Report a vulnerability (a private security advisory). Include what you found, how to reproduce it, the version or commit, and what an attacker gains. If that option is not available, open a public issue that says only that you have a security report and want a private channel.

Expect an acknowledgement within about 7 days. There is no bug bounty. OpenMHS has not been security audited; the threat model is in docs/security.

License and conduct

OpenMHS is licensed under Apache-2.0. By submitting a contribution you agree to license it under the same terms; there is no separate CLA. By taking part you agree to follow the Code of Conduct. For help, see SUPPORT.md.