| Message ID | 20260903-kbingham-abi-trailers-v1-2-72ae051c912a@ideasonboard.com |
|---|---|
| State | New |
| Headers | show |
| Series |
|
| Related | show |
Hi Kieran, Thank you for the patch. On Thu, Sep 03, 2026 at 03:51:51PM +0100, Kieran Bingham wrote: > Document the requirement to specify when commits knowingly change either > the ABI or public API of libcamera. > > Future enhancements to the CI infrastructure can use these tags to > accept changes which knowingly break the ABI/API and prevent unknown ABI > or API breakages to be merged. > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > --- > Documentation/contributing.rst | 21 +++++++++++++++++++++ > 1 file changed, 21 insertions(+) > > diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst > index 20682d56c75d..2588da4e224d 100644 > --- a/Documentation/contributing.rst > +++ b/Documentation/contributing.rst > @@ -71,6 +71,27 @@ Freedesktop also provides our CI and `testing pipeline`_. > > .. _testing pipeline: https://gitlab.freedesktop.org/camera/libcamera/-/pipelines > > +ABI and API Stability > +--------------------- > + > +We provide a script `./utils/abi-compat.sh` which can be run to detect and > +report any ABI or API breakage in the public interfaces. > + > +Contributions which knowingly break the ABI or API should specify this in the > +commit message with one of the following trailer examples. It's not clear what format we expect. Does it have to be the output of abi-compat.sh ? Is anything allowed ? > + > +The CI testing suite may choose to reject contributions which cause an ABI or > +API breakage but do not specify the effect in the commit log. > + > +:: > + > + ABI: struct IPAModuleInfo: > + Field pipelineName has been removed from the middle position of this > + structural type. Multi-line trailers are more difficult to parse. How do you plan to consume this information ? > + > + API: struct IPAModuleInfo: > + Field pipelineName has been removed from this type. > + > Issue Tracker > ------------- >
Quoting Laurent Pinchart (2026-10-19 13:39:04) > Hi Kieran, > > Thank you for the patch. > > On Thu, Sep 03, 2026 at 03:51:51PM +0100, Kieran Bingham wrote: > > Document the requirement to specify when commits knowingly change either > > the ABI or public API of libcamera. > > > > Future enhancements to the CI infrastructure can use these tags to > > accept changes which knowingly break the ABI/API and prevent unknown ABI > > or API breakages to be merged. > > > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > > --- > > Documentation/contributing.rst | 21 +++++++++++++++++++++ > > 1 file changed, 21 insertions(+) > > > > diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst > > index 20682d56c75d..2588da4e224d 100644 > > --- a/Documentation/contributing.rst > > +++ b/Documentation/contributing.rst > > @@ -71,6 +71,27 @@ Freedesktop also provides our CI and `testing pipeline`_. > > > > .. _testing pipeline: https://gitlab.freedesktop.org/camera/libcamera/-/pipelines > > > > +ABI and API Stability > > +--------------------- > > + > > +We provide a script `./utils/abi-compat.sh` which can be run to detect and > > +report any ABI or API breakage in the public interfaces. > > + > > +Contributions which knowingly break the ABI or API should specify this in the > > +commit message with one of the following trailer examples. > > It's not clear what format we expect. Does it have to be the output of > abi-compat.sh ? Is anything allowed ? At the moment, I don't think it matters too much - as long as the details are highlighted. To me the 'ABI:' part is the flag to say "ABI has changed in this commit" The additional parts are for a person. > > > + > > +The CI testing suite may choose to reject contributions which cause an ABI or > > +API breakage but do not specify the effect in the commit log. > > + > > +:: > > + > > + ABI: struct IPAModuleInfo: > > + Field pipelineName has been removed from the middle position of this > > + structural type. > > Multi-line trailers are more difficult to parse. How do you plan to > consume this information ? Fortunately - as a human, I'm quite capable of reading multiple lines. My goal is to be able to use this information when preparing release notes. -- Kieran > > > + > > + API: struct IPAModuleInfo: > > + Field pipelineName has been removed from this type. > > + > > Issue Tracker > > ------------- > > > > -- > Regards, > > Laurent Pinchart
On Mon, Oct 19, 2026 at 02:37:15PM +0100, Kieran Bingham wrote: > Quoting Laurent Pinchart (2026-10-19 13:39:04) > > On Thu, Sep 03, 2026 at 03:51:51PM +0100, Kieran Bingham wrote: > > > Document the requirement to specify when commits knowingly change either > > > the ABI or public API of libcamera. > > > > > > Future enhancements to the CI infrastructure can use these tags to > > > accept changes which knowingly break the ABI/API and prevent unknown ABI > > > or API breakages to be merged. > > > > > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > > > --- > > > Documentation/contributing.rst | 21 +++++++++++++++++++++ > > > 1 file changed, 21 insertions(+) > > > > > > diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst > > > index 20682d56c75d..2588da4e224d 100644 > > > --- a/Documentation/contributing.rst > > > +++ b/Documentation/contributing.rst > > > @@ -71,6 +71,27 @@ Freedesktop also provides our CI and `testing pipeline`_. > > > > > > .. _testing pipeline: https://gitlab.freedesktop.org/camera/libcamera/-/pipelines > > > > > > +ABI and API Stability > > > +--------------------- > > > + > > > +We provide a script `./utils/abi-compat.sh` which can be run to detect and > > > +report any ABI or API breakage in the public interfaces. > > > + > > > +Contributions which knowingly break the ABI or API should specify this in the > > > +commit message with one of the following trailer examples. > > > > It's not clear what format we expect. Does it have to be the output of > > abi-compat.sh ? Is anything allowed ? > > At the moment, I don't think it matters too much - as long as the > details are highlighted. To me the 'ABI:' part is the flag to say "ABI > has changed in this commit" > > The additional parts are for a person. If it's free-formed, I feel it would be better to include the explanation in the body of the commit message in a free-formed way, and use a standardized trailer that just flags the ABI/API breakage. > > > + > > > +The CI testing suite may choose to reject contributions which cause an ABI or > > > +API breakage but do not specify the effect in the commit log. > > > + > > > +:: > > > + > > > + ABI: struct IPAModuleInfo: > > > + Field pipelineName has been removed from the middle position of this > > > + structural type. > > > > Multi-line trailers are more difficult to parse. How do you plan to > > consume this information ? > > Fortunately - as a human, I'm quite capable of reading multiple lines. > > My goal is to be able to use this information when preparing release > notes. I'd like to make sure that the tag can also be easily parsed. git-inspect-trailers seems to support multi-line trailers, but isn't very easy to use. It wouldn't be rocket-science to roll out a manual implementation in Python, but the ability to just simply grep would be nice. Would it be an issue to start with single-line trailers ? > > > + > > > + API: struct IPAModuleInfo: > > > + Field pipelineName has been removed from this type. > > > + > > > Issue Tracker > > > ------------- > > >
Quoting Laurent Pinchart (2026-10-19 14:50:31) > On Mon, Oct 19, 2026 at 02:37:15PM +0100, Kieran Bingham wrote: > > Quoting Laurent Pinchart (2026-10-19 13:39:04) > > > On Thu, Sep 03, 2026 at 03:51:51PM +0100, Kieran Bingham wrote: > > > > Document the requirement to specify when commits knowingly change either > > > > the ABI or public API of libcamera. > > > > > > > > Future enhancements to the CI infrastructure can use these tags to > > > > accept changes which knowingly break the ABI/API and prevent unknown ABI > > > > or API breakages to be merged. > > > > > > > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > > > > --- > > > > Documentation/contributing.rst | 21 +++++++++++++++++++++ > > > > 1 file changed, 21 insertions(+) > > > > > > > > diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst > > > > index 20682d56c75d..2588da4e224d 100644 > > > > --- a/Documentation/contributing.rst > > > > +++ b/Documentation/contributing.rst > > > > @@ -71,6 +71,27 @@ Freedesktop also provides our CI and `testing pipeline`_. > > > > > > > > .. _testing pipeline: https://gitlab.freedesktop.org/camera/libcamera/-/pipelines > > > > > > > > +ABI and API Stability > > > > +--------------------- > > > > + > > > > +We provide a script `./utils/abi-compat.sh` which can be run to detect and > > > > +report any ABI or API breakage in the public interfaces. > > > > + > > > > +Contributions which knowingly break the ABI or API should specify this in the > > > > +commit message with one of the following trailer examples. > > > > > > It's not clear what format we expect. Does it have to be the output of > > > abi-compat.sh ? Is anything allowed ? > > > > At the moment, I don't think it matters too much - as long as the > > details are highlighted. To me the 'ABI:' part is the flag to say "ABI > > has changed in this commit" > > > > The additional parts are for a person. > > If it's free-formed, I feel it would be better to include the > explanation in the body of the commit message in a free-formed way, and > use a standardized trailer that just flags the ABI/API breakage. > > > > > + > > > > +The CI testing suite may choose to reject contributions which cause an ABI or > > > > +API breakage but do not specify the effect in the commit log. > > > > + > > > > +:: > > > > + > > > > + ABI: struct IPAModuleInfo: > > > > + Field pipelineName has been removed from the middle position of this > > > > + structural type. > > > > > > Multi-line trailers are more difficult to parse. How do you plan to > > > consume this information ? > > > > Fortunately - as a human, I'm quite capable of reading multiple lines. > > > > My goal is to be able to use this information when preparing release > > notes. > > I'd like to make sure that the tag can also be easily parsed. > git-inspect-trailers seems to support multi-line trailers, but isn't > very easy to use. It wouldn't be rocket-science to roll out a manual > implementation in Python, but the ability to just simply grep would be > nice. Would it be an issue to start with single-line trailers ? No, Just tell me what single line you expect. -- Kieran > > > > > + > > > > + API: struct IPAModuleInfo: > > > > + Field pipelineName has been removed from this type. > > > > + > > > > Issue Tracker > > > > ------------- > > > > > > -- > Regards, > > Laurent Pinchart
diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst index 20682d56c75d..2588da4e224d 100644 --- a/Documentation/contributing.rst +++ b/Documentation/contributing.rst @@ -71,6 +71,27 @@ Freedesktop also provides our CI and `testing pipeline`_. .. _testing pipeline: https://gitlab.freedesktop.org/camera/libcamera/-/pipelines +ABI and API Stability +--------------------- + +We provide a script `./utils/abi-compat.sh` which can be run to detect and +report any ABI or API breakage in the public interfaces. + +Contributions which knowingly break the ABI or API should specify this in the +commit message with one of the following trailer examples. + +The CI testing suite may choose to reject contributions which cause an ABI or +API breakage but do not specify the effect in the commit log. + +:: + + ABI: struct IPAModuleInfo: + Field pipelineName has been removed from the middle position of this + structural type. + + API: struct IPAModuleInfo: + Field pipelineName has been removed from this type. + Issue Tracker -------------
Document the requirement to specify when commits knowingly change either the ABI or public API of libcamera. Future enhancements to the CI infrastructure can use these tags to accept changes which knowingly break the ABI/API and prevent unknown ABI or API breakages to be merged. Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> --- Documentation/contributing.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)