Merge pull #679: Dev Docs: "Not A Specification"

_includes/guide_intro.md

@@ -6,7 +6,8 @@ http://opensource.org/licenses/MIT.
 {% autocrossref %}
 
 The Developer Guide aims to provide the information you need to understand
-Bitcoin and start building Bitcoin-based applications. To make the best use of
+Bitcoin and start building Bitcoin-based applications, but it is [not a
+specification][]. To make the best use of
 this documentation, you may want to install the current version of Bitcoin
 Core, either from [source][core git] or from a [pre-compiled executable][core executable].
 

_includes/guide_p2p_network.md

@@ -226,6 +226,7 @@ These messages are aggressively broadcast using the `alert` message, being sent
 
 These messages are signed by a specific ECDSA private key that only a small number of developers control. 
 
-**Resource:** More details about the structure of messages and a complete list of message types can be found at the [Protocol Specification](https://en.bitcoin.it/wiki/Protocol_specification) page of the Bitcoin Wiki.
+**Resource:** More details about the structure of messages and a complete list of message types can be found in
+the [P2P reference section][section P2P reference].
 
 {% endautocrossref %}

_includes/ref_intro.md

@@ -2,11 +2,13 @@
 This file is licensed under the MIT License (MIT) available on
 http://opensource.org/licenses/MIT.
 {% endcomment %}
+{% assign filename="_includes/ref_intro.md" %}
 
 {% autocrossref %}
 
-The Developer Reference aims to provide specifications and API information
+The Developer Reference aims to provide technical details and API information
-to help you start building Bitcoin-based applications. To make the best use of
+to help you start building Bitcoin-based applications, but it is [not a
+specification][]. To make the best use of
 this documentation, you may want to install the current version of Bitcoin
 Core, either from [source][core git] or from a [pre-compiled executable][core executable].
 
@@ -23,3 +25,44 @@ links will be shown in blue.  If you hover over a cross-reference link, a brief
 definition of the term will be displayed in a tooltip.
 
 {% endautocrossref %}
+
+#### Not A Specification
+{:.no_toc}
+{% include helpers/subhead-links.md %}
+
+{% autocrossref %}
+
+The Bitcoin.org Developer Documentation describes how Bitcoin works to
+help educate new Bitcoin developers, but it is not a specification---and
+it never will be.
+
+Bitcoin security depends on consensus. Should your program diverge from
+consensus, its security is weakened or destroyed. The cause of the
+divergence doesn't matter: it could be a bug in your program, it could
+be an [error in this documentation][errors in docs] which you
+implemented as described, or it could be you do everything right but
+other software on the network [behaves unexpectedly][v0.8 chain
+fork]. The specific cause will not matter to the users of your software
+whose wealth is lost.
+
+The only correct specification of consensus behavior is the actual
+behavior of programs on the network which maintain consensus. As that
+behavior is subject to arbitrary inputs<!--noref--> in a large variety
+of unique environments, it cannot ever be fully documented here or
+anywhere else.
+
+However, the Bitcoin Core developers are working on making their
+consensus code portable so other implementations can use it. Bitcoin
+Core 0.10 will provide `libbitcoinconsensus`, a first attempt at
+exporting some consensus code. Future versions of Bitcoin Core will
+likely provide consensus code that is more complete, more portable, and
+more consistent in diverse environments.
+
+In addition, we also warn you that this documentation has not been
+extensively reviewed by Bitcoin experts and so likely contains numerous
+errors. At the bottom of the menu on the left, you will find links that
+allow you to report an issue or to edit the documentation on GitHub.
+Please use those links if you find any errors or important missing
+information.
+
+{% endautocrossref %}

_includes/ref_p2p_networking.md

@@ -9,8 +9,8 @@ http://opensource.org/licenses/MIT.
 
 {% autocrossref %}
 
-This section describes the Bitcoin P2P network protocol (but it is not a
+This section describes the Bitcoin P2P network protocol (but it is [not a
-specification). It does not describe the discontinued direct [IP-to-IP
+specification][]). It does not describe the discontinued direct [IP-to-IP
 payment protocol][], the [BIP70 payment protocol][payment protocol], the
 [GetBlockTemplate mining protocol][section getblocktemplate], or any
 network protocol never implemented in an official version of Bitcoin Core.

_includes/references.md

@@ -300,6 +300,7 @@ http://opensource.org/licenses/MIT.
 [locktime parsing rules]: /en/developer-guide#locktime_parsing_rules
 [Merge Avoidance subsection]: /en/developer-guide#merge-avoidance
 [micropayment channel]: /en/developer-guide#term-micropayment-channel
+[not a specification]: /en/developer-reference#not-a-specification
 [raw transaction format]: /en/developer-reference#raw-transaction-format
 [RPC]: /en/developer-reference#remote-procedure-calls-rpcs
 [RPCs]: /en/developer-reference#remote-procedure-calls-rpcs
@@ -309,12 +310,14 @@ http://opensource.org/licenses/MIT.
 [section hash byte order]: /en/developer-reference#hash-byte-order
 [section merkle trees]: /en/developer-reference#merkle-trees
 [section merkleblock example]: /en/developer-examples#parsing-a-merkleblock
+[section p2p reference]: /en/developer-reference#p2p-network
 [section protocol versions]: /en/developer-reference#protocol-versions
 [section serialized blocks]: /en/developer-reference#serialized-blocks
 [section simple raw transaction]: /en/developer-examples#simple-raw-transaction
 [section verifying payment]: /en/developer-guide#verifying-payment
 [signature script modification warning]: /en/developer-reference#signature_script_modification_warning
 [transaction object format]: /en/developer-reference#term-transaction-object-format
+[v0.8 chain fork]: /en/alert/2013-03-11-chain-fork
 [Verification subsection]: /en/developer-guide#verifying-payment
 [X509Certificates]: /en/developer-examples#term-x509certificates
 
@@ -371,6 +374,7 @@ http://opensource.org/licenses/MIT.
 [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_DSA
 [Electrum server]: https://github.com/spesmilo/electrum-server
 [Eloipool]: https://gitorious.org/bitcoin/eloipool
+[errors in docs]: https://github.com/bitcoin/bitcoin.org/issues?q=is%3Aissue+label%3A%22Dev+Docs%22
 [forum tech support]: https://bitcointalk.org/index.php?board=4.0
 [high-speed block relay network]: https://www.mail-archive.com/bitcoin-development@lists.sourceforge.net/msg03189.html
 [HMAC-SHA512]: https://en.wikipedia.org/wiki/HMAC

en/developer-documentation.md

@@ -14,7 +14,7 @@ title: "Developer Documentation - Bitcoin"
 
 <div class="docreference">
 <a href="/en/developer-guide"><img src="/img/icons/main_ico_compass.svg" alt="icon"><span>Developer Guide</span><span>(How Bitcoin works)</span></a>
-<a href="/en/developer-reference"><img src="/img/icons/main_ico_guide.svg" alt="icon"><span>Developer Reference</span><span>(Specifications and APIs)</span></a>
+<a href="/en/developer-reference"><img src="/img/icons/main_ico_guide.svg" alt="icon"><span>Developer Reference</span><span>(Technical details and APIs)</span></a>
 <a href="/en/developer-examples"><img src="/img/icons/main_ico_hash.svg" alt="icon"><span>Developer Examples</span><span>(Examples you can use)</span></a>
 </div>
 

en/developer-reference.md

@@ -10,7 +10,7 @@ title: "Developer Reference - Bitcoin"
 
 # Bitcoin Developer Reference
 
-<p class="summary">Find technical specifications and API documentation.</p>
+<p class="summary">Find technical details and API documentation.</p>
 
 <div markdown="1" id="toc" class="toc"><div markdown="1">