Hi All, I wanted to send a follow-up mail to the C API discussion/BoF that we had at the latest developer meeting and nicely hosted by Justin and Juergen. We were able to reach consensus on a number of questions/concerns about the C API so I’m going to go ahead and list them for posterity and for any further discussion here: 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 on the 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 the release 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. Please feel free to follow up to this thread with any concerns. Thanks! -eric (with Justin and Juergen) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20151119/5de64bcc/attachment.html>
+1 Philip On 11/19/2015 01:56 PM, Eric Christopher via llvm-dev wrote:> > Hi All, > > I wanted to send a follow-up mail to the C API discussion/BoF that we > had at the latest developer meeting and nicely hosted by Justin and > Juergen. > > We were able to reach consensus on a number of questions/concerns > about the C API so I’m going to go ahead and list them for posterity > and for any further discussion here: > > 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 on > the 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 the > release 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. > > Please feel free to follow up to this thread with any concerns. > > Thanks! > > -eric (with Justin and Juergen) > > > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20151119/d4f1edf3/attachment.html>
Thanks for helping get all of this sorted out and documented, Eric (and Juergen and Justin). As you’ve laid things out, this does a great job of both documenting our existing practice and breaking out the different use-cases and how they related to stability. That’s hugely useful, as the differences are not always obvious and have historically given rise to frustration and confusion. Similarly, I’m glad to see made explicit both expectations regarding unit tests for APIs and for proposing extensions to or new APIs. All of this makes great sense. -Jim> On Nov 19, 2015, at 1:56 PM, Eric Christopher via llvm-dev <llvm-dev at lists.llvm.org> wrote: > > > Hi All, > > I wanted to send a follow-up mail to the C API discussion/BoF that we had at the latest developer meeting and nicely hosted by Justin and Juergen. > > We were able to reach consensus on a number of questions/concerns about the C API so I’m going to go ahead and list them for posterity and for any further discussion here: > > 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 on the 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 the release 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. > > Please feel free to follow up to this thread with any concerns. > > Thanks! > > -eric (with Justin and Juergen) > > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20151119/f00ea6e5/attachment-0001.html>
Are you going to propagate this info into http://llvm.org/docs/DeveloperPolicy.html ? On Thu, Nov 19, 2015 at 1:56 PM, Eric Christopher via llvm-dev < llvm-dev at lists.llvm.org> wrote:> > Hi All, > > I wanted to send a follow-up mail to the C API discussion/BoF that we had > at the latest developer meeting and nicely hosted by Justin and Juergen. > > We were able to reach consensus on a number of questions/concerns about > the C API so I’m going to go ahead and list them for posterity and for any > further discussion here: > > 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 on the 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 the > release 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. > > Please feel free to follow up to this thread with any concerns. > > Thanks! > > -eric (with Justin and Juergen) > > > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev > >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20151119/29c1eadf/attachment.html>
"Documentation: We’re going to document this policy in the developer documentation. In addition, any changes to the C API will require documentation in the release notes so that it’s clear to external users who do not follow the project how the C API is changing and evolving." So, yes? -eric On Thu, Nov 19, 2015 at 5:55 PM Sean Silva <chisophugis at gmail.com> wrote:> Are you going to propagate this info into > http://llvm.org/docs/DeveloperPolicy.html ? > > On Thu, Nov 19, 2015 at 1:56 PM, Eric Christopher via llvm-dev < > llvm-dev at lists.llvm.org> wrote: > >> >> Hi All, >> >> I wanted to send a follow-up mail to the C API discussion/BoF that we had >> at the latest developer meeting and nicely hosted by Justin and Juergen. >> >> We were able to reach consensus on a number of questions/concerns about >> the C API so I’m going to go ahead and list them for posterity and for any >> further discussion here: >> >> 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 on the >> 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 the >> release 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. >> >> Please feel free to follow up to this thread with any concerns. >> >> Thanks! >> >> -eric (with Justin and Juergen) >> >> >> _______________________________________________ >> LLVM Developers mailing list >> llvm-dev at lists.llvm.org >> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >> >>-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20151120/89c58cd8/attachment.html>