README: Add a section on working with libpldm
9d2a1c6ad095 ("libpldm: Explicit deprecated, stable and testing ABI
classes") gave us the ability to merge new APIs without having to review
them to death before merging. Now we can merge and iterate on an API
before locking into the library's ABI.
Given this, document how people should consume the library, and
expectations on developers contributing to the library.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: Ida0c691e48f3885d12039755994cf5dfeefa5206
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f008bb9..a8ed54d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,10 +20,12 @@
### Added
1. Add encode/decode pldmMessagePollEvent data
+2. README: Add a section on working with libpldm
### Changed
1. include: Move installed transport.h under libpldm/
+2. libpldm: Explicit deprecated, stable and testing ABI classes
### Fixed
diff --git a/README.md b/README.md
index d3b6611..91f9ace 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,120 @@
meson setup builddir && meson test -C builddir
```
+## Working with `libpldm`
+
+The ABIs (symbols, generally functions) exposed by the library are separated
+into three categories:
+
+1. Stable
+2. Testing
+3. Deprecated
+
+Applications depending on `libpldm` should aim to only use functions from the
+stable category. However, this may not always be possible. What to do when
+required functions fall into the deprecated or testing categories is outlined
+below.
+
+### The ABI lifecycle
+
+```mermaid
+---
+title: libpldm symbol lifecycle
+---
+stateDiagram-v2
+ direction LR
+ [*] --> Testing: Add
+ Testing --> Testing: Change
+ Testing --> [*]: Remove
+ Testing --> Stable: Stabilise
+ Stable --> Deprecated: Deprecate
+ Deprecated --> [*]: Remove
+```
+
+The ABI of the library produced by the build is controlled using the `abi` meson
+option. The following use cases determine how the `abi` option should be
+specified:
+
+| Use Case | Meson Configuration |
+| ----------- | --------------------------------- |
+| Production | `-Dabi=deprecated,stable` |
+| Maintenance | `-Dabi=stable` |
+| Development | `-Dabi=deprecated,stable,testing` |
+
+### Maintenance
+
+Applications and libraries that depend on `libpldm` can identify how to migrate
+off of deprecated APIs by constraining the library ABI to the stable category.
+This will force the compiler identify any call-sites that try to link against
+deprecated symbols.
+
+### Development
+
+Applications and libraries often require functionality that doesn't yet exist in
+`libpldm`. The work is thus in two parts:
+
+1. Add the required APIs to `libpldm`
+2. Use the new APIs from `libpldm` in the dependent application or library
+
+Adding APIs to a library is a difficult task. Generally, once an API is exposed
+in the library's ABI, any changes to the API risk breaking applications already
+making use of it. To make sure we have more than one shot at getting an API
+right, all new APIs must first be exposed in the testing category. Concretely:
+
+Patches adding new APIs MUST mark them as testing and MUST NOT mark them as
+stable.
+
+### Marking functions as testing, stable or deprecated
+
+Three macros are provided through `config.h` to mark functions as testing,
+stable or deprecated:
+
+1. `LIBPLDM_ABI_TESTING`
+2. `LIBPLDM_ABI_STABLE`
+3. `LIBPLDM_ABI_DEPRECATED`
+
+These annotations go immediately before your function signature:
+
+```c
+#include "config.h"
+
+...
+
+LIBPLDM_ABI_TESTING
+pldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport,
+ pldm_tid_t tid,
+ const void *pldm_req_msg,
+ size_t req_msg_len)
+{
+ ...
+}
+```
+
+### Requirements for stabilising a function
+
+As mentioned above, all new functions must first be added in the testing
+category (using the `LIBPLDM_ABI_TESTING` annotation).
+
+To move a function from the testing category to the stable category, its
+required that patches demonstrating use of the function in a dependent
+application or library be linked in the commit message of the stabilisation
+change. We require this to demonstrate that the implementer has considered its
+use in context _before_ preventing us from making changes to the API.
+
+### Building a dependent application or library against a testing ABI
+
+Meson is broadly used in the OpenBMC ecosystem, the historical home of
+`libpldm`. Meson's subprojects are a relatively painless way of managing
+dependencies for the purpose of developing complex applications and libraries.
+Use of `libpldm` as a subproject is both supported and encouraged.
+
+`libpldm`'s ABI can be controlled from a parent project through meson's
+subproject configuration syntax:
+
+```shell
+$ meson setup ... -Dlibpldm:abi=deprecated,stable,testing ...
+```
+
## OEM/vendor-specific functions
This will support OEM or vendor-specific functions and semantic information.