Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.
98 changes: 86 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <version>`.
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
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
Loading