[cfe-dev] [3.8 Release] Please write release notes!

[Eric Christopher via cfe-dev]

>
>
> - Eric: should the new C API Changes part of the developer policy be
> pointed out? Maybe in relation to where we mention changes to the C
> API?
>
>
Good point, how about this:

----

We have documented our C API stability guarantees for both development and
release branches, as well as documented how to extend the C API. Please see
the developer documentation at
http://llvm.org/docs/DeveloperPolicy.html#c-api-changes for more
information.

----

Or if we feel like being verbose you can add the following from my original
email to the release notes:

----

Stability Guarantees:

The C API is, in general, a “best effort” for stability. This means that
we’ll make every attempt to keep the C API stable, but that stability will
be limited by the abstractness of the interface and the stability of the C
++ API that it wraps. In practice, this means that things like “create
debug info” or “create this type of instruction” is likely to be less
stable than “take this IR file and JIT it for my current machine”.
Release stability:
We won’t break the C API on the release branch with patches that go on that
branch - in general.
Exception: If we fix an unintentional C API break that will keep us
consistent with both the previous and next release.

Including new things into the API:

We’re going to adopt a policy of “if a particular LLVM subcomponent has a C
API already included, then expanding that API is acceptable”, but we’re
also going to institute a better policy of “please test the API that you’ve
just expanded”. Hopefully this will get the C API better tested as time
goes on to remove accidental breakage so that any time we break the C API we
know about it.

Adding C API for subcomponents that don’t currently have one is also fine,
and the details of how best to do that should be discussed onthe mailing
list as they come up.

Documentation:

We’re going to document this policy in the developer documentation. In
addition, any changes to the C API will require documentation in therelease
notes so that it’s clear to external users who do not follow the project
how the C API is changing and evolving.

What we expect this means in practice is that APIs like libLTO and other
APIs based on reading IR are going to remain highly stable and that more
wrapper like APIs (IR creation, etc) are going to both be added and change
as the underlying IR changes.

----

Thoughts?

Thanks!

-eric
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20160301/d2164bf5/attachment.html>