<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p.msonormal0, li.msonormal0, div.msonormal0
{mso-style-name:msonormal;
mso-margin-top-alt:auto;
margin-right:0in;
mso-margin-bottom-alt:auto;
margin-left:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal">I agree that a documented C++ api stability policy would be valuable. Since the policy seems to be “the API is not stable”, it would be helpful to have it written down for when people push back on changes because they would cause API breakages.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I would think the “Introducing new things into the API” section would say something to the effect of “features may be added with impunity, subject to code review”. Though since new features added to an API without removing other things
does not represent any sort of breakage, maybe it doesn’t bear mentioning in a section about API stability.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Thanks,<o:p></o:p></p>
<p class="MsoNormal"> Christopher Tetreault<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b>From:</b> llvm-dev <llvm-dev-bounces@lists.llvm.org> <b>On Behalf Of
</b>Varun Gandhi via llvm-dev<br>
<b>Sent:</b> Tuesday, July 21, 2020 5:17 PM<br>
<b>To:</b> llvm-dev@lists.llvm.org<br>
<b>Subject:</b> [EXT] [llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?<o:p></o:p></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">The Developer Policy document (<a href="https://llvm.org/docs/DeveloperPolicy.html">https://llvm.org/docs/DeveloperPolicy.html</a>) contains a Section "C API Changes". There is no corresponding section for C++ API Changes. LLVM is somewhat
different from most libraries in that the main language is C++ but the C++ API is not guaranteed to be stable in any shape or form from what I understand.<o:p></o:p></p>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">I think it would be useful to have a "C++ API Changes" section to Developer Policy spelling this out. Copying the style of the C API Changes section, it could look something like:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">---<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">C++ API Changes<br>
<br>
* <span style="color:black">Stability Guarantees: The C++ API is does not guarantee any stability. Changes may be made without any notice about deprecation and alternate APIs for the same functionality may not be included. Downstream projects using the C++
API are expected to keep up with changes.</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="color:black">* Release stability: The C++ API does not make any stability guarantees for the release branch.</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="color:black">* Testing: Patches to the C++ API are expected to come with tests just like any other patch.</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="color:black">* Including new things into the API: [TODO: I'm not sure what should go here].</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="color:black">* </span>Documentation: Changes to the C++ API are not expected to be documented in the release notes.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">---<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Clang does have a page with information about its own C++ API (<a href="https://clang.llvm.org/docs/Tooling.html">https://clang.llvm.org/docs/Tooling.html</a>) which is more informative, but I think it would useful to have this information
on the Developer Policy page for the whole of LLVM.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Does this addition sound reasonable?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Varun<o:p></o:p></p>
</div>
</div>
</body>
</html>