<div dir="ltr"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
- Eric: should the new C API Changes part of the developer policy be<br>
pointed out? Maybe in relation to where we mention changes to the C<br>
API?<br><br></blockquote><div><br></div><div>Good point, how about this:</div><div><br></div><div>----</div><div><br></div><div>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 <a href="http://llvm.org/docs/DeveloperPolicy.html#c-api-changes">http://llvm.org/docs/DeveloperPolicy.html#c-api-changes</a> for more information.</div><div><br></div><div>----</div><div><br></div><div>Or if we feel like being verbose you can add the following from my original email to the release notes:</div><div><br></div><div>----</div><div><br></div><div><span style="font-size:13px;line-height:19.5px">Stability Guarantees:</span></div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px"><span class="lG">The</span> <span class="lG">C</span> <span class="lG">API</span> is, in general, a “best effort” for stability. This means that we’ll make every attempt to keep <span class="lG">the</span> <span class="lG">C</span> <span class="lG">API</span> stable, but that stability will be limited by <span class="lG">the</span> abstractness of <span class="lG">the</span> interface and <span class="lG">the</span> stability of <span class="lG">the</span> <span class="lG">C</span>++ <span class="lG">API</span> 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”.</div><div style="font-size:13px;line-height:19.5px">Release stability:</div><div style="font-size:13px;line-height:19.5px">We won’t break <span class="lG">the</span> <span class="lG">C</span> <span class="lG">API</span> <span class="lG">on</span> <span class="lG">the</span> release branch with patches that go <span class="lG">on</span> that branch - in general.</div><div style="font-size:13px;line-height:19.5px">Exception: If we fix <span class="lG">an</span> unintentional <span class="lG">C</span> <span class="lG">API</span> break that will keep us consistent with both <span class="lG">the</span> previous and next release.</div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px">Including new things into <span class="lG">the</span> <span class="lG">API</span>:</div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px">We’re going to adopt a policy of “if a particular LLVM subcomponent has a <span class="lG">C</span> <span class="lG">API</span> already included, then expanding that <span class="lG">API</span> is acceptable”, but we’re also going to institute a better policy of “please test <span class="lG">the</span> <span class="lG">API</span> that you’ve just expanded”. Hopefully this will get <span class="lG">the</span> <span class="lG">C</span> <span class="lG">API</span> better tested as time goes <span class="lG">on</span> to remove accidental breakage so that any time we break <span class="lG">the</span> <span class="lG">C</span> <span class="lG">API</span> we know about it.</div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px">Adding <span class="lG">C</span> <span class="lG">API</span> for subcomponents that don’t currently have one is also fine, and <span class="lG">the</span> details of how best to do that should be discussed <span class="lG">on</span><span class="lG">the</span> mailing list as they come up.</div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px">Documentation:</div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px">We’re going to document this policy in <span class="lG">the</span> developer documentation. In addition, any changes to <span class="lG">the</span> <span class="lG">C</span> <span class="lG">API</span> will require documentation in <span class="lG">the</span>release notes so that it’s clear to external users who do not follow <span class="lG">the</span> project how <span class="lG">the</span> <span class="lG">C</span> <span class="lG">API</span> is changing and evolving.</div><div style="font-size:13px;line-height:19.5px"><br></div><div style="font-size:13px;line-height:19.5px">What we expect this means in practice is that <span class="lG">APIs</span> like libLTO and other <span class="lG">APIs</span> based <span class="lG">on</span> reading IR are going to remain highly stable and that more wrapper like <span class="lG">APIs</span> (IR creation, etc) are going to both be added and change as <span class="lG">the</span> underlying IR changes.</div><div><br></div><div>----</div><div><br></div><div>Thoughts?</div><div><br></div><div>Thanks!</div><div><br></div><div>-eric</div></div></div>