Announcement: API summaries coming to a FIDL library near you

[Filip Filmar]

tl;dr: if you don't care about FIDL API evolution, you can stop reading now.

Hello all.

A while ago, we started adding companion *.api_summary files with a human readable summary of a FIDL API alongside all FIDL libraries. To give an example, the FIDL library fuchsia.intl has its summary in //sdk/fidl/fuchsia.intl/fuchsia.intl.api_summary.

Starting Jul 29, 2021, we are also enforcing that the *.api_summary files are in sync with the respective libraries.  If you make an API impacting change, the build process will ask you to update the summary file, and will print a hopefully helpful command line that allows you to semi-automate that work.

As a result, whenever you change a FIDL library, in the gerrit diff you will get a helpful diff that explains the effect of the change to the API surface.  Also, the changes that do not impact the API, such as changes to the documentation, will not result in the changes to the API summary.  The API summaries will be used in the future to automate the detection of API impacting changes.

And for completeness: a few weeks ago, we started using the contents of the *.api_summary files to compute the FIDL API signatures. If you noticed that you no longer need to update *.api files manually when you make non-API-impacting changes to FIDL, that is why.

Let me know if you notice any issues with the enforcement.

Cheers,
F