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

[Hal Finkel via llvm-dev]

On 7/23/20 9:13 AM, David Chisnall via llvm-dev wrote:
> 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


This is also my understanding. We maintain ABI stability across patch 
releases.

  -Hal


>
> 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
>>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

-- 
Hal Finkel
Lead, Compiler Technology and Programming Languages
Leadership Computing Facility
Argonne National Laboratory