[llvm] r213813 - Document what backwards compatibility we provide for bitcode.

[Rafael Espindola]

Author: rafael
Date: Wed Jul 23 17:43:22 2014
New Revision: 213813

URL: http://llvm.org/viewvc/llvm-project?rev=213813&view=rev
Log:
Document what backwards compatibility we provide for bitcode.

Modified:
    llvm/trunk/docs/DeveloperPolicy.rst

Modified: llvm/trunk/docs/DeveloperPolicy.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/DeveloperPolicy.rst?rev=213813&r1=213812&r2=213813&view=diff
==============================================================================
--- llvm/trunk/docs/DeveloperPolicy.rst (original)
+++ llvm/trunk/docs/DeveloperPolicy.rst Wed Jul 23 17:43:22 2014
@@ -436,6 +436,29 @@ list, development list, or LLVM bug trac
 a patch privately, encourage them to submit it to the appropriate list first.
 
 
+IR Backwards Compatibility
+--------------------------
+
+When the IR format has to be changed, keep in mind that we try to maintain some
+backwards compatibility. The rules are intended as a balance between convenience
+for llvm users and not imposing a big burden on llvm developers:
+
+* The textual format is not backwards compatible. We don't change it too often,
+  but there are no specific promises.
+
+* The bitcode format produced by a X.Y release will be readable by all following
+  X.Z releases and the (X+1).0 release.
+
+* Newer releases can ignore features from older releases, but they cannot
+  miscompile them. For example, if nsw is ever replaced with something else,
+  dropping it would be a valid way to upgrade the IR.
+
+* Debug metadata is special in that it is currently dropped during upgrades.
+
+* Non-debug metadata is defined to be safe to drop, so a valid way to upgrade
+  it is to drop it. That is not very user friendly and a bit more effort is
+  expected, but no promises are made.
+
 .. _copyright-license-patents:
 
 Copyright, License, and Patents