Contributing to AIP

Thank you for improving Agent Interoperability Protocol. AIP is both a versioned wire contract and a Rust implementation, so a change is complete only when its protocol, code, schema, tests, and documentation remain consistent.

Before You Start

• Read the documentation home, architecture overview, and AIP 1.0 specification.
• Use Rust 1.88 or newer and the stable toolchain selected by rust-toolchain.toml.
• Keep the implementation clean-room. Do not copy or import code from the historical obsolete prototype archived outside this workspace.
• Report security vulnerabilities through the private process in SECURITY.md, not a public issue.

Architecture Boundaries

• Native semantic types belong in aip-core; product and compatibility DTOs do not.
• aip-runtime owns lifecycle, persistence contracts, policy enforcement, recovery, and operational queries.
• Profiles translate external protocols. Connectors translate external products. Neither may redefine native AIP semantics.
• Transports frame and carry protocol messages; authorization decisions belong at authenticated gateway/runtime boundaries.
• Public integrations use the frozen aip-connector SDK and declare only the behavior they actually implement and test.

See the dependency graph before adding a new crate edge.

Development Workflow

1. Create a focused branch from the current mainline.
2. Add or update tests before claiming behavior is complete.
3. Keep public APIs documented in English with examples where an API is not self-evident.
4. Run formatting and the narrow tests for the changed crates while iterating.
5. Run the repository gates before requesting review.
6. Describe behavioral, compatibility, security, storage, and deployment impact in the change summary.

Do not mix generated artifacts, local state, credentials, qualification logs, or unrelated refactors into a protocol change.

Protocol and Schema Changes

A wire-visible or semantic change must update all applicable artifacts:

• normative text in docs/spec/AIP-1.0.md;
• the Rust semantic model and validation rules;
• generated schemas under schemas/aip;
• positive and negative conformance fixtures;
• compatibility mappings affected by the change;
• task-oriented guides and reference pages;
• CHANGELOG.md and, for a design change, an RFC or ADR.

Run schema generation and drift checks through the existing xtask commands. Never edit a generated schema alone and leave the Rust source model unchanged. Backward-incompatible changes require the versioning process defined by the specification; they must not silently alter a stable message family.

Connector Changes

Connector work must use authenticated TrustedActionContext, typed ConnectorFailure, declared implementation support, idempotency and cancellation semantics, secret redaction, and the frozen conformance driver. Follow Build a Connector and, for an older integration, Upgrade a Connector.

External-provider qualification is evidence for the exact source, image, configuration, and provider revision tested. Deterministic unit tests do not replace an isolated-live campaign, and historical evidence does not automatically qualify a rebuilt artifact.

Required Checks

Run the complete workspace checks for release-affecting changes:

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo test --workspace --no-default-features
cargo doc --workspace --all-features --no-deps
cargo run -p xtask -- release-check

Run applicable integration, conformance, external interoperability, storage, restart, fault, and load campaigns when the change affects those boundaries. Optional release tools are documented in tools/ci/README.md.

Documentation Standard

• Write code, comments, schemas, RFCs, and documentation in English.
• Explain user intent and operational consequences, not only type names.
• Keep commands copyable and distinguish source-checkout, installed-binary, local-development, and production usage.
• Link to the normative rule instead of duplicating it inconsistently.
• Mark implementation and qualification limits explicitly. Do not use “production-ready” as a synonym for “implemented” or “tests pass.”
• Add new user-facing documents to docs/SUMMARY.md.

Review Evidence

A review request should state:

• the problem and chosen boundary;
• protocol and API compatibility impact;
• security and tenant-isolation impact;
• migrations or recovery behavior;
• commands and tests run, with relevant exact artifacts;
• documentation and schema changes;
• remaining risks or intentionally unsupported behavior.

Reviewers should reject claims that are broader than their retained evidence.