diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf946d2e..4b19cd8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -186,6 +186,62 @@ guidelines: - If you're not sure what to name it, pick any name and we can help you with it. +### Borrowing Request Types + +In order to reduce the number of `.clone()`s necessary to send requests +to a server, we support borrowed types for request types. (We hope to support +borrowing in response types sometime, but that is dependent on GATs.) + +#### Types to borrow + +| Field type | Borrowed type | Notes | +| ---------- | ------------- | ----- | +| strings | `&'a str` | | +| identifiers | `&'a IdentifierType` | | +| `Vec<_>` | `&'a [_]` | The inner type should not be borrowed. | + +#### Types not to borrow + +Inner types of `Vec`s _should not_ be borrowed, nor should `BTreeMap`s and such. + +Structs also should not be borrowed, with the exception that if a struct: + +- has fields that should be borrowed according to the table +above (strings, identifiers, `Vec`s), and +- is only used inside request blocks (i.e. not in response blocks or in +events), + +then the struct should be lifetime-parameterized and apply the same rules to +their fields. So instead of + +```rust +ruma_api! { + request: { + my_field: MyStruct, + } + // ... +} + +pub struct MyStruct { + inner_string_field: String, +} +``` + +use + +```rust +ruma_api! { + request: { + my_field: MyStruct<'a> + } + // ... +} + +pub struct MyStruct<'a> { + inner_string_field: &'a str, +} +``` + ### Tracking Changes If your changes affect the API of a user-facing crate (all except the `-macros` crates and