Merge pull request #1072 from ethereum/versioning

Document versioning behaviour

1 files changed, 26 insertions, 0 deletions

diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst
index ad27e528..ebb7537b 100644
--- a/docs/installing-solidity.rst
+++ b/docs/installing-solidity.rst
@@ -6,6 +6,15 @@
 Installing Solidity
 ###################
 
+Versioning
+==========
+
+Solidity versions follow `semantic versioning <https://semver.org>` and in addition to
+releases, **nightly development builds** are also made available.  The nightly builds
+are not guaranteed to be working and despite best efforts they might contain undocumented
+and/or broken changes. We recommend to use the latest release. Package installers below
+will use the latest release.
+
 Browser-Solidity
 ================
 
@@ -186,3 +195,20 @@ Alternatively, you can build for Windows on the command-line, like so:
 .. code:: bash
 
     cmake --build . --config RelWithDebInfo
+
+Important information about versioning
+======================================
+
+After a release is made, the patch version level is bumped, because we assume that only
+patch level changes follow. When changes are merged, the version should be bumped according
+to semver and the severity of the change. Finally, a release is always made with the version
+of the current nightly build, but without the ``prerelease`` specifier.
+
+Example:
+- 0) the 0.4.0 release is made
+- 1) nightly build has a version of 0.4.1 from now on
+- 2) non-breaking changes are introduced - no change in version
+- 3) a breaking change is introduced - version is bumped to 0.5.0
+- 4) the 0.5.0 release is made
+
+This behaviour works well with the version pragma.