From 7a5bb662b560c748cf166222276cc68b52283346 Mon Sep 17 00:00:00 2001 From: Eric Christopher Date: Thu, 10 Dec 2015 21:33:53 +0000 Subject: [PATCH] Add C API guidelines to the developer policy to match discussions on the llvm mailing lists. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@255300 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/DeveloperPolicy.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst index ea498dde459..5eac458b8e7 100644 --- a/docs/DeveloperPolicy.rst +++ b/docs/DeveloperPolicy.rst @@ -525,6 +525,33 @@ for llvm users and not imposing a big burden on llvm developers: it is to drop it. That is not very user friendly and a bit more effort is expected, but no promises are made. +C API Changes +---------------- + +* Stability Guarantees: The C API is, in general, a “best effort” for stability. +This means that we make every attempt to keep the C API stable, but that +stability will be limited by the abstractness of the interface and the stability +of the C++ API that it wraps. In practice, this means that things like “create +debug info” or “create this type of instruction” are likely to be less stable +than “take this IR file and JIT it for my current machine”. + +* Release stability: We won’t break the C API on the release branch with patches +that go on that branch, with the exception that if we will fix an unintentional +C API break that will keep the release consistent with both the previous and next +release. + +* Testing: Patches to the C API are expected to come with tests just like any +other patch. + +* Including new things into the API: If an LLVM subcomponent has a C API already +included, then expanding that C API is acceptable. Adding C API for subcomponents +that don't currently have one is fine, and the details of how best to design that +API should be discussed on the mailing list. + +* Documentation: Any changes to the C API are required to be documented in the +release notes so that it’s clear to external users who do not follow the project +how the C API is changing and evolving. + .. _copyright-license-patents: Copyright, License, and Patents -- 2.34.1