Thanks for your interest in contributing to function-sdk-rust!
This project follows the governance and community guidelines of the broader Crossplane project. See OWNERS.md for the current maintainer(s) and CODE_OF_CONDUCT.md for expected community behavior.
See the README for the repository layout and the README for an introduction to the SDK.
You need a stable Rust toolchain. Regenerating code also needs protoc on
your PATH.
# Format.
cargo fmt --all
# Lint. CI fails on warnings.
cargo clippy --workspace --tests -- -D warnings
# Run tests.
cargo test --workspace
# Regenerate sdk/src/generated from the vendored proto.
cargo run -p codegenCI 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 or
sdk/tests/generated differ from what's checked in.
Don't edit sdk/src/generated or sdk/tests/generated by hand. Change the
proto or codegen/, then run codegen and commit the result.
prost discards a field it doesn't know, so codegen replaces prost's Message
derive. codegen/src/messages.rs gives every message an unknown_fields
field and writes the impls the derive would have written, with the unknown
fields kept and encoded again. Codegen also writes the messages as prost
derives them to sdk/tests/generated/prost_v1.rs.
sdk/tests/generated_messages.rs compares the two for every message: the
bytes, the errors on malformed input, Debug, the defaults and the
accessors.
sdk/proto/v1/run_function.proto is a copy of the file in
crossplane/crossplane. 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:
- Replace the file with the one from the release tag, and put the
Vendored from crossplane/crossplanecomment back abovesyntaxwith the new version. - Run
cargo run -p codegenand commit the changes insdk/src/generatedandsdk/tests/generated. - Set each new field in the samples of
sdk/tests/generated_messages.rs. A sample lists every field of its message, so that file doesn't compile until you do. - If codegen stops at a field kind it doesn't write yet, its error gives
the field and the
#[prost(...)]attribute. Add the kind tocodegen/src/messages.rs, following what prost's derive generates for it. - If the update adds a message,
the_checks_cover_every_message_of_the_protofails. Add the message tofor_every_messageand tosampleinsdk/tests/generated_messages.rs. - 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.
Renovate merges minor, patch and digest updates by itself once the checks pass. Major updates and proto updates wait for a maintainer.
Once a week Renovate also refreshes Cargo.lock within the ranges the
manifests allow and merges that the same way. An indirect dependency has no
line in a manifest, so this refresh is how a fix in one arrives. The lock
file is the repository's own: a function that depends on the SDK resolves
its dependencies itself.
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.
A new version of prost can change what its Message derive does. Its pull
request then fails in sdk/tests/generated_messages.rs, and
codegen/src/messages.rs has to follow the derive before it merges.
- 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, and reference any related issue in the description.
- Write commit subjects as Conventional Commits, for
example
fix(logging): honor RUST_LOG. Mark a breaking change with!and aBREAKING CHANGE:footer. - Sign off every commit with
git commit -s. The DCO check fails without theSigned-off-byline. - 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.
Maintainers release from the main branch:
- Decide the version. While the crate is 0.x, a breaking change raises the minor version and anything else raises the patch version.
- Open a pull request that sets
versioninsdk/Cargo.tomland updatesCargo.lock, titledchore(sdk): bump version to <version>. - After it merges, run the
Publishworkflow with the version prefixed byv, for examplev0.5.0. The workflow refuses a version that doesn't matchsdk/Cargo.toml, publishes the crate to crates.io, and creates the GitHub release with generated notes.
Please see SECURITY.md instead of opening a public issue.