diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3d5b965 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# Agents + +Instructions for AI agents working in this repository. Read +[CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or a pull request; +it describes the workflows these rules refer to. + +## What this is + +A Rust SDK for Crossplane composition functions: generated protocol types, a +gRPC server runtime, and request and response helpers. The +[README](README.md#layout) describes the layout. + +## Checks + +Run all of these before you call a change done. CI requires them. + +```shell +cargo fmt --all --check +cargo clippy --workspace --tests -- -D warnings +cargo test --workspace +cargo run -p codegen # needs protoc; must leave sdk/src/generated unchanged +``` + +## Rules + +- Never edit `sdk/src/generated` by hand. Change the proto or `codegen/` and + regenerate. +- `State` and `Resource` are written by hand in `sdk/src/proto/state.rs`. + When the proto changes either message, update that file and + `sdk/tests/unknown_fields.rs` as CONTRIBUTING.md describes. +- A new public field on a message struct is a breaking change. Say so in the + commit and the pull request. +- Don't change the crate version outside a release pull request. +- Keep the SDK's behaviour aligned with function-sdk-go, and record a + deliberate difference in the README section on differences. +- Sign off and sign every commit, and write Conventional Commits subjects. +- One logical change per pull request. Don't mix in unrelated fixes. +- Don't publish, tag or run the `Publish` workflow. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79cde21..d3fbac2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,32 +14,106 @@ See the [README](README.md#layout) for the repository layout and the ## Development +You need a stable Rust toolchain. Regenerating code also needs `protoc` on +your `PATH`. + ```shell -# Run tests. -cargo test +# Format. +cargo fmt --all -# Lint. -cargo clippy --workspace --tests +# Lint. CI fails on warnings. +cargo clippy --workspace --tests -- -D warnings -# Regenerate sdk/src/generated from the vendored proto (requires protoc). +# Run tests. +cargo test --workspace + +# Regenerate sdk/src/generated from the vendored proto. cargo run -p codegen ``` -The `State` and `Resource` messages are written by hand in -`sdk/src/proto/state.rs` so that they keep unknown fields. When an update of -the vendored proto changes either message, update that file to match; a test -fails until you do. +CI runs four checks on every pull request, and all four must pass before it +can merge: `fmt`, `clippy`, `test` and `codegen-drift`. The last one runs +codegen and fails when the `.rs` files in `sdk/src/generated` differ from +what's checked in. + +### Generated and hand-written protocol code + +Don't edit `sdk/src/generated` by hand. Change the proto or `codegen/`, then +run codegen and commit the result. + +Two messages aren't generated. `State` and `Resource` are written by hand in +`sdk/src/proto/state.rs` so that they keep fields this SDK doesn't know, +which prost-generated messages discard. Codegen skips both and adds +`unknown_fields` to their generated serde constructors. + +### Updating the vendored proto + +`sdk/proto/v1/run_function.proto` is a copy of the file in +[crossplane/crossplane][proto]. A comment above its `syntax` line names the +release it was copied from. Renovate reads that comment and opens a pull +request when Crossplane publishes a newer release. That pull request changes +only the version in the comment, so Renovate doesn't merge it by itself. +Finish it on its branch: + +1. Replace the file with the one from the release tag, and put the + `Vendored from crossplane/crossplane` comment back above `syntax` with the + new version. +2. Run `cargo run -p codegen` and commit the changes in `sdk/src/generated`. + New fields on generated messages need nothing else. +3. If the update changes `State` or `Resource`, the build fails in the + generated serde code and a test in `sdk/tests/unknown_fields.rs` fails. + Update `sdk/src/proto/state.rs` to match: the struct field, `encode_raw`, + `merge_field`, `encoded_len`, and `Debug` for `Resource`. Then update the + prost-derived copies and the expected field list in that test file. +4. Run the checks above. + +A new field on any message is a breaking change for this crate, because the +message structs are public and can be built with a struct literal. Say so in +the pull request so the next release gets the right version. + +### Dependency updates + +Renovate merges minor, patch and digest updates by itself once the checks +pass. Major updates and proto updates wait for a maintainer. + +A new version of `prost-build`, `tonic-prost-build` or `pbjson-build` can +change the generated code, and its pull request then fails `codegen-drift`. +Check out the branch, run `cargo run -p codegen`, and push the result to the +same branch. ## Submitting changes * Open an issue first for anything beyond a small fix, so we can agree on the approach before you invest time in it. -* Keep pull requests focused on a single logical change. -* Make sure `cargo test` and `cargo clippy --workspace --tests` pass. -* Reference any related issue in the pull request description. +* Keep pull requests focused on a single logical change, and reference any + related issue in the description. +* Write commit subjects as [Conventional Commits][conventional-commits], for + example `fix(logging): honor RUST_LOG`. Mark a breaking change with `!` + and a `BREAKING CHANGE:` footer. +* Sign off every commit with `git commit -s`. The DCO check fails without + the `Signed-off-by` line. +* Sign your commits. The main branch only accepts verified signatures. +* Add or update tests for behaviour you change, and update the README when + the public API or a documented behaviour changes. +* Don't change the crate version in a feature pull request. + +## Releasing + +Maintainers release from the main branch: + +1. Decide the version. While the crate is 0.x, a breaking change raises the + minor version and anything else raises the patch version. +2. Open a pull request that sets `version` in `sdk/Cargo.toml` and updates + `Cargo.lock`, titled `chore(sdk): bump version to `. +3. After it merges, run the `Publish` workflow with the version prefixed by + `v`, for example `v0.5.0`. The workflow refuses a version that doesn't + match `sdk/Cargo.toml`, publishes the crate to crates.io, and creates the + GitHub release with generated notes. ## Reporting security issues Please see [SECURITY.md](SECURITY.md) instead of opening a public issue. [governance]: https://github.com/crossplane/crossplane/blob/main/GOVERNANCE.md +[proto]: https://github.com/crossplane/crossplane/tree/main/proto/fn/v1 +[conventional-commits]: https://www.conventionalcommits.org diff --git a/README.md b/README.md index 088bade..4e0a3b4 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,9 @@ cargo clippy --workspace --tests cargo run -p codegen ``` +See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks CI runs, how to update +the vendored proto, and how releases are made. + The vendored proto's canonical source is [crossplane/crossplane/proto/fn/v1][proto]. Only the v1 API is supported, which requires Crossplane v1.17 or later. @@ -132,6 +135,12 @@ with a few deliberate differences: in a prometheus-client `Registry` built with a version semver-compatible with the SDK's (the same minor version while prometheus-client is 0.x). +## Agents + +If you are an AI agent helping with this repository, read +[AGENTS.md](AGENTS.md) before making changes and read +[CONTRIBUTING.md](CONTRIBUTING.md) before opening issues or PRs. + [crossplane]: https://www.crossplane.io [functions]: https://docs.crossplane.io/latest/composition/compositions/ [function-sdk-python]: https://github.com/crossplane/function-sdk-python