From 31f74d5b6f3134ba8f9da36a84b2aa90df241085 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonasz=20Ma=C5=82ecki?= Date: Thu, 19 Nov 2026 09:56:48 +0100 Subject: [PATCH] docs: add AGENTS.md and expand CONTRIBUTING.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Describe the checks CI requires, the generated and hand-written protocol code, how to update the vendored proto, how dependency updates merge, the commit rules, and the release steps. AGENTS.md gives AI agents the short version and the README points to both files. Signed-off-by: Jonasz MaƂecki --- AGENTS.md | 38 +++++++++++++++++++ CONTRIBUTING.md | 98 +++++++++++++++++++++++++++++++++++++++++++------ README.md | 9 +++++ 3 files changed, 133 insertions(+), 12 deletions(-) create mode 100644 AGENTS.md 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