[PATCH] D12685: Document the stability policy for LLVM-C APIs.

[James Y Knight via llvm-commits]

jyknight created this revision.
jyknight added reviewers: ributzka, lhames, echristo, deadalnix.
jyknight added a subscriber: llvm-commits.

("Reasonably stable, not 100% guaranteed")

This is my proposal, following from the thread "[RFC] Developer Policy
for LLVM C API".

Please comment, bikeshed, and/or flame, as appropriate. Initial
reviewers chosen from a few interested parties from the email thread,
but I dunno what the policy actually is for making policy changes.

http://reviews.llvm.org/D12685

Files:
  docs/DeveloperPolicy.rst

Index: docs/DeveloperPolicy.rst
===================================================================
--- docs/DeveloperPolicy.rst
+++ docs/DeveloperPolicy.rst
@@ -525,6 +525,67 @@
   it is to drop it. That is not very user friendly and a bit more effort is
   expected, but no promises are made.
 
+LLVM-C API Compatibility
+------------------------
+
+While most of LLVM's library API is explicitly lacking any sort of cross-version
+compatibility/API-stability guarantees, the API exposed by the headers in
+``include/llvm-c/`` are covered by a somewhat enhanced compatibility policy.
+
+This policy is designed to make life easier for users calling into LLVM -- both
+those using the ``.h`` file from C or C++ code, and those doing a
+foreign-function-call from some other programming language.
+
+LVM can not and does not promise absolute forward or backwards compatibility for
+the LLVM-C API, or even a n-release deprecation policy, because we do not want
+these compatibility rules to slow development on the underlying LLVM
+functionality. And on the other hand, we also do not want to restrict the APIs
+covered by the LLVM-C API to only those which can be guaranteed to "never"
+change. That would be too limiting to be useful.
+
+So, here are some guidelines:
+
+* The ABI/signature of an existing function *must* not be modified. That
+  includes adding arguments, removing arguments, changing the types of
+  arguments, etc.  If a function needs a new signature, instead create a new
+  function with a new name.
+
+  Making this sort of incompatible change could cause hard-to-diagnose ABI
+  incompatibilites, which not only hurts cross-release ABI compatibility, but
+  also hurts users who are calling the APIs from another language, and will not
+  necessarily get an obvious error to notify them of such a change.
+
+* New functions exposing new LLVM functionality may be added to the LLVM-C API
+  "as needed". Functions for a part of the API already exposed should generally
+  be accepted with simple code review, and *may* be done at the same time as
+  adding the underlying LLVM functionality, if the developer so
+  desires. (e.g. exposing a LLVMBuild* function for a new IR feature would fall
+  under this category.)
+
+  Be a little more careful when exposing an as-yet-unexposed part of LLVM. There
+  is a cost to the compatibility policy, and it is not necessarily a good idea
+  for rapidly-changing or less-generally-useful parts of LLVM's API to be
+  exposed.
+
+* Functions *should not* be removed from the LLVM-C API, but *may* be removed
+  after careful consideration, when required. For example, if the underlying
+  LLVM functionality is being removed, there is no realistic and useful way to
+  keep an LLVM-C wrapper for it.
+
+  Similarly, the older variants of a function should be kept when introducing
+  new variants (e.g. ``LLVMIntTypeInContext`` effectively replaces
+  ``LLVMIntType``, but ``LLVMIntType`` is not removed). However, if is not
+  reasonably possible to preserve the old function, it may be removed.
+
+  Marking a function "deprecated" for some time before its final removal is
+  appreciated, but is not a strict requirement.
+
+* Similar rules follow for enum elements: they must not be renumbered, but may
+  be added and, if necessary, removed. Be aware that removing an enum element
+  can not prevent existing callers from continuing to pass it as input to
+  functions! Also, be careful not to cause the underlying integer type of the
+  enum to change (e.g. by adding a value that doesn't fit in a 32-bit int).
+
 .. _copyright-license-patents:
 
 Copyright, License, and Patents


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D12685.34189.patch
Type: text/x-patch
Size: 3654 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150908/f9b129b4/attachment.bin>