1# Checklist for making changes to `libpldm` 2 3## Definitions 4 5- Public API: Any definitions and declarations under `include/libpldm` 6 7## Adding a new API 8 9- [ ] My new public `struct` definitions are _not_ marked 10 `__attribute__((packed))` 11 12- [ ] If my work interacts with the PLDM wire format, then I have done so using 13 the `msgbuf` APIs found in `src/msgbuf.h` (and under `src/msgbuf/`) to 14 minimise concerns around spatial memory safety and endian-correctness. 15 16- [ ] If I've added support for a new PLDM message type, then I've implemented 17 both the encoder and decoder for that message. Note this applies for both 18 request _and_ response message types. 19 20- [ ] My new function symbols are marked with `LIBPLDM_ABI_TESTING` in the 21 implementation 22 23- [ ] I've implemented test cases with reasonable branch coverage of each new 24 function I've added 25 26- [ ] I've guarded the test cases of functions marked `LIBPLDM_ABI_TESTING` so 27 that they are not compiled when the corresponding function symbols aren't 28 visible 29 30- [ ] If I've added support for a new message type, then my commit message 31 specifies all of: 32 33 - [ ] The relevant DMTF specification by its DSP number and title 34 - [ ] The relevant version of the specification 35 - [ ] The section of the specification that defines the message type 36 37- [ ] If my work impacts the public API of the library, then I've added an entry 38 to `CHANGELOG.md` describing my work 39 40## Stabilising an existing API 41 42- [ ] The API of interest is currently marked `LIBPLDM_ABI_TESTING` 43 44- [ ] My commit message links to a publicly visible patch that makes use of the 45 API 46 47- [ ] My commit updates the annotation from `LIBPLDM_ABI_TESTING` to 48 `LIBPLDM_ABI_STABLE` only for the function symbols demonstrated by the 49 patch linked in the commit message. 50 51- [ ] I've removed guards from the function's tests so they are always compiled 52 53- [ ] If I've updated the ABI dump, then I've used the OpenBMC CI container to 54 do so. 55 56## Updating an ABI dump 57 58Each of the following must succeed: 59 60- [ ] Enter the OpenBMC CI Docker container 61 - Approximately: 62 `docker run --cap-add=sys_admin --rm=true --privileged=true -u $USER -w $(pwd) -v $(pwd):$(pwd) -e MAKEFLAGS= -it openbmc/ubuntu-unit-test:2024-W21-ce361f95ff4fa669` 63- [ ] `CC=gcc CXX=g++; [ $(uname -m) = 'x86_64' ] && meson setup -Dabi=deprecated,stable build` 64- [ ] `meson compile -C build` 65- [ ] `cp build/src/current.dump abi/x86_64/gcc.dump` 66 67## Removing an API 68 69- [ ] If the function is marked `LIBPLDM_ABI_TESTING`, then I have removed it 70 71- [ ] If the function is marked `LIBPLDM_ABI_STABLE`, then I have changed the 72 annotation to `LIBPLDM_ABI_DEPRECATED` and left it in-place. 73 74- [ ] If the function is marked `LIBPLDM_ABI_DEPRECATED`, then I have removed it 75 only after satisfying myself that each of the following is true: 76 77 - [ ] There are no known users of the function left in the community 78 - [ ] There has been at least one tagged release of `libpldm` subsequent to 79 the API being marked deprecated 80 81## Testing my changes 82 83Each of the following must succeed when executed in order. Note that to avoid 84[googletest bug #4232][googletest-issue-4232] you must avoid using GCC 12 85(shipped in Debian Bookworm). 86 87[googletest-issue-4232](https://github.com/google/googletest/issues/4232) 88 89- [ ] `meson setup -Dabi-compliance-check=disabled build` 90- [ ] `meson compile -C build && meson test -C build` 91 92- [ ] `meson configure --buildtype=release build` 93- [ ] `meson compile -C build && meson test -C build` 94 95- [ ] `meson configure --buildtype=debug build` 96- [ ] `meson configure -Dabi=deprecated,stable build` 97- [ ] `meson compile -C build && meson test -C build` 98