docs: checklists: Document heap allocation constraint
Almost all of the APIs punt allocation to the caller or use iterators
to avoid forcing it altogether. Note this in the changes checklist so
contributors have a shot at designing desirable APIs from the outset.
Change-Id: I3d815d4c5bd1e67fa6248933feab365fff0ba2ca
Signed-off-by: Andrew Jeffery <andrew@codeconstruct.com.au>
diff --git a/docs/checklists/changes.md b/docs/checklists/changes.md
index fdcf690..a2b689b 100644
--- a/docs/checklists/changes.md
+++ b/docs/checklists/changes.md
@@ -124,6 +124,18 @@
- This applies for both request _and_ response message types.
+- [ ] I've designed my APIs so their implementation does not require heap
+ allocation.
+
+ - Prefer [defining iterators][libpldm-iterator] over the message buffer to
+ extract sub-structures from variable-length messages. Iterators avoid both
+ requiring heap allocation in the implementation or splitting the API to
+ allow the caller to allocate appropriate space. Instead, the caller is
+ provided with an on-stack struct containing the extracted sub-structure.
+
+[libpldm-iterator]:
+ https://github.com/openbmc/libpldm/commit/3a2c6589c5660d2066b612bae28ca393a8aa1c2b
+
- [ ] My new public message codec functions take a `struct` representing the
message as a parameter