Typo and more explanation.

3 files changed, 45 insertions, 25 deletions

diff --git a/docs/bugs.json b/docs/bugs.json
index d50cf597..f80816ee 100644
--- a/docs/bugs.json
+++ b/docs/bugs.json
@@ -27,7 +27,7 @@
         "fixed": "0.4.4"
     },
     {
-        "name": "StaleKnowledegAboutSHA3",
+        "name": "StaleKnowledgeAboutSHA3",
         "summary": "The optimizer did not properly reset its knowledge about SHA3 operations resulting in some hashes (also used for storage variable positions) not being calculated correctly.",
         "description": "The optimizer performs symbolic execution in order to save re-evaluating expressions whose value is already known. This knowledge was not properly reset across control flow paths and thus the optimizer sometimes thought that the result of a SHA3 operation is already present on the stack. This could result in data corruption by accessing the wrong storage slot.",
         "severity": "low/medium",
diff --git a/docs/bugs.rst b/docs/bugs.rst
index be7544d0..083759f3 100644
--- a/docs/bugs.rst
+++ b/docs/bugs.rst
@@ -6,12 +6,32 @@
 List of Known Bugs
 ##################
 
-Below, you can find a JSON-formatted list of all known security-relevant bugs in the
+Below, you can find a JSON-formatted list of known security-relevant bugs in the
 Solidity compiler. The file itself is hosted in the `Github repository
 <https://github.com/ethereum/solidity/blob/develop/docs/bugs.json>`_.
 The list stretches back as far as version 0.3.0, bugs known to be present only
-in previous versions are not listed. The JSON file is an array of objects, one for
-each bug, with the following keys:
+in versions preceding that are not listed.
+
+There is another file called `bugs_by_version.json
+<https://github.com/ethereum/solidity/blob/develop/docs/bugs_by_version.json>`_,
+which can be used to check which bugs affect a specific version of the compiler.
+
+Contract source verification tools and also other tools interacting with
+contracts should consult this list according to the following criteria:
+
+ - It is mildly suspicious if a contract was compiled with a nightly
+   compiler version instead of a released version. These compiler versions
+   might contain undocumented bugs.
+ - It is also mildly suspicious if a contract was compiled with a version that was
+   not the most recent at the time the contract was created. For contracts
+   created from other contracts, you have to follow the creation chain
+   back to a transaction and use the date of that transaction as creation date.
+ - It is highly suspicious if a contract was compiled with a compiler that
+   contains a known bug and the contract was created at a time where a newer
+   compiler version containing a fix was already released.
+
+The JSON file of known bugs below is an array of objects, one for each bug,
+with the following keys:
 
 name
     Unique name given to the bug
diff --git a/docs/bugs_by_version.json b/docs/bugs_by_version.json
index 55df848d..5d119807 100644
--- a/docs/bugs_by_version.json
+++ b/docs/bugs_by_version.json
@@ -2,7 +2,7 @@
     "0.1.0": {
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -15,7 +15,7 @@
     "0.1.1": {
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -28,7 +28,7 @@
     "0.1.2": {
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -41,7 +41,7 @@
     "0.1.3": {
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -54,7 +54,7 @@
     "0.1.4": {
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -67,7 +67,7 @@
     "0.1.5": {
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -81,7 +81,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -95,7 +95,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -109,7 +109,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -123,7 +123,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -137,7 +137,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -151,7 +151,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -164,7 +164,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -176,7 +176,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin", 
@@ -188,7 +188,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin"
@@ -199,7 +199,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin"
@@ -210,7 +210,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther", 
             "DynamicAllocationInfiniteLoop", 
             "ClearStateOnCodePathJoin"
@@ -221,7 +221,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "SendFailsForZeroEther"
         ], 
         "released": "2016-08-10"
@@ -230,7 +230,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "LibrariesNotCallableFromPayableFunctions"
         ], 
         "released": "2016-09-08"
@@ -239,7 +239,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3", 
+            "StaleKnowledgeAboutSHA3", 
             "LibrariesNotCallableFromPayableFunctions"
         ], 
         "released": "2016-09-09"
@@ -252,7 +252,7 @@
         "bugs": [
             "IdentityPrecompileReturnIgnored", 
             "HighOrderByteCleanStorage", 
-            "StaleKnowledegAboutSHA3"
+            "StaleKnowledgeAboutSHA3"
         ], 
         "released": "2016-09-17"
     },