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

[Chris Tetreault via llvm-dev]

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.

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.

Thanks,
   Christopher Tetreault

From: llvm-dev <llvm-dev-bounces at lists.llvm.org> On Behalf Of Varun Gandhi via llvm-dev
Sent: Tuesday, July 21, 2020 5:17 PM
To: llvm-dev at lists.llvm.org
Subject: [EXT] [llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?

The Developer Policy document (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 just like 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) 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200722/1bfc1d9f/attachment.html>