Version pragma.

1 files changed, 30 insertions, 1 deletions

diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
index 6ef06961..3697fdfb 100644
--- a/docs/layout-of-source-files.rst
+++ b/docs/layout-of-source-files.rst
@@ -2,7 +2,36 @@
 Layout of a Solidity Source File
 ********************************
 
-Source files can contain an arbitrary number of contract definitions and include directives.
+Source files can contain an arbitrary number of contract definitions, include directives
+and pragma directives.
+
+.. index:: ! pragma, version
+
+Version Pragma
+==============
+
+Source files can (and should) be annotated with a so-called version pragma to reject
+being compiled with future compiler versions that might introduce incompatible
+changes. We try to keep such changes at an absolute minimum and especially
+introduce changes in a way that changes in semantics will also require changes
+in the syntax, but this is of course not always possible. Because of that, it is always
+a good idea to read through the changelog at least for releases that contain
+breaking changes, those releases will always have versions of the form
+``0.x.0`` or ``x.0.0``.
+
+The version pragma is used as follows::
+
+  pragma solidity ^0.4.0;
+
+Such a source file will not compile with a compiler earlier than version 0.4.0
+and it will also not work on a compiler starting form version 0.5.0 (this
+second condition is added by using ``^``). The idea behind this is that
+there will be no breaking changes until version ``0.5.0``, so we can always
+be sure that our code will compile the way we intended it to. We do not fix
+the exact version of the compiler, so that bugfix releases are still possible.
+
+It is possible to specify much more complex rules for the compiler version,
+the expression follows those used by npm.
 
 .. index:: source file, ! import