Skip to content

Latest commit

 

History

History
119 lines (90 loc) · 4.83 KB

CONTRIBUTING.md

File metadata and controls

119 lines (90 loc) · 4.83 KB

Contributing

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.

Getting started

See the README for the repository layout and the README for an introduction to the SDK.

Development

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 codegen

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. 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, 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 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 instead of opening a public issue.