[llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?

[David Chisnall via llvm-dev]

I believe the policy is to provide ABI stability across the patch 
releases so that any downstream distribution that ships LLVM X can also 
ship LLVM X.0.Y and pick up bug fixes.  There is no stability guarantee 
even at the source level between LLVM X and LLVM X+1, though where 
possible it's considered polite to deprecate things and provide a 
migration path.  In practice, quite a lot of LLVM now has backwards API 
(source) compatibility across versions but still retains the option of 
breaking this in any release.

David

On 23/07/2020 12:57, Sam Elliott via llvm-dev wrote:
> Something that would be good to get clarity on:
> 
> The RISC-V backend recently had a bugfix patch that got backported to 
> the 10.0.1 branch. The original patch introduced a new virtual method in 
> TargetLowering.h, and the backported patch [1] was rewritten to avoid 
> changing the ABI of libLLVM.so.
> 
> This feels like some kind of policy decision about the C++ ABI beyond 
> "it's entirely unstable" - though I understand we may not want to commit 
> to doing this for every backported bug fix.
> 
> It would be good to understand where this line is, if we're going to 
> clarify the documentation.
> 
> Sam
> 
> [1]: 
> https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f 
> <https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f>
> 
>> On 23 Jul 2020, at 4:52 am, Chris Lattner via llvm-dev 
>> <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote:
>>
>> This sounds reasonable to me, I am generally +1 on documenting things 
>> that are well known but not written down.
>>
>> Thanks Varun!
>>
>> -Chris
>>
>>> On Jul 21, 2020, at 5:16 PM, Varun Gandhi via llvm-dev 
>>> <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote:
>>>
>>> The Developer Policy document 
>>> (https://llvm.org/docs/DeveloperPolicy.html 
>>> <https://llvm.org/docs/DeveloperPolicy.html>) 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.
>>>
>>> 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:
>>>
>>> ---
>>> C++ API Changes
>>>
>>> * 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.
>>> * Release stability: The C++ API does not make any stability 
>>> guarantees for the release branch.
>>> * Testing: Patches to the C++ API are expected to come with tests 
>>> justlike any other patch.
>>> * Including new things into the API: [TODO: I'm not sure what should 
>>> go here].
>>> * Documentation: Changes to the C++ API are not expected to be 
>>> documented in the release notes.
>>> ---
>>>
>>> Clang does have a page with information about its own C++ API 
>>> (https://clang.llvm.org/docs/Tooling.html 
>>> <https://clang.llvm.org/docs/Tooling.html>) which is more 
>>> informative, but I think it would useful to have this information on 
>>> the Developer Policy page for the whole of LLVM.
>>>
>>> Does this addition sound reasonable?
>>>
>>> Varun
>>> _______________________________________________
>>> LLVM Developers mailing list
>>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>
>>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev 
>>> <https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev>
>>
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
> 
> --
> Sam Elliott
> Software Team Lead
> Senior Software Developer - LLVM and OpenTitan
> lowRISC CIC
> 
> 
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>