/bitcoin.org

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Dev Docs: "Not A Specification" #679

Merged
merged 3 commits into from Dec 19, 2014

Conversation

Reviewers
No reviews
Assignees
No one assigned
Labels
Dev Docs
Projects
None yet
Milestone
No milestone
2 participants
@harding @saivann
@harding
Contributor

harding commented Dec 12, 2014

Preview: http://dg0.dtrt.org/en/developer-reference#not-a-specification

Make explicit that the docs are not a specification and never will be:

  • Add a new section to the DevRef entitled "Not A Specification". See preview link above
  • In the first sentence of both the DevGuide and the DevRef, say "but [this] is not a specification", with not a specification linked to the new section.
  • Remove other mentions of specification in the doc

This is inspired by @gmaxwell's recent BitcoinTalk post about protocol standardization. @gmaxwell: I'd appreciate it if you could review the new section preview linked above; it's only 5 short paragraphs.

@harding harding added the Dev Docs label Dec 12, 2014

@saivann saivann commented on the diff Dec 12, 2014

View full changes
_includes/ref_intro.md
+whose wealth is lost.
+
+The only correct specification of consensus behavior is the actual
+program behavior of the majority software on the network. 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
@saivann

saivann Dec 12, 2014

Contributor

Maybe instead the always-visible disclaimer could be updated to be a bit more explicit that the documentation likely still contains many errors (and the "has been written recently" part may not be accurate anymore)?

@harding

harding Dec 12, 2014

Contributor

Good idea. I'll put updating that disclaimer in a separate pull. Thanks!

@saivann saivann and 1 other commented on an outdated diff Dec 12, 2014

View full outdated diff
_includes/ref_intro.md
+
+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 the
+majority 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
+program behavior of the majority software on the network. As that
@saivann

saivann Dec 12, 2014

Contributor

Maybe we could drop "majority", or use "overwhelming majority"? Majority usually means 50%+1. I feel this could be confusing given that forks obey to different specifications and which specification will "win" usually depends on people running the software agreeing on where the fault is or what is the right thing to do.

@harding

harding Dec 12, 2014

Contributor

Yeah, it is confusing. How about:

The only correct specification of consensus behavior is the actual behavior of programs on the network that maintain consensus.

Likewise, in the paragraph above it, s/the majority software/other software/

@saivann

saivann Dec 12, 2014

Contributor

Sounds good to me

@saivann saivann commented on the diff Dec 12, 2014

View full changes
_includes/ref_intro.md
@@ -23,3 +24,43 @@ 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}
+
+{% 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
@saivann

saivann Dec 12, 2014

Contributor

@harding Unless you stop being incredibly responsive as you currently are, I think this link will usually point to an empty list :)

@harding

harding Dec 12, 2014

Contributor

Oh, old issues should show up in that link. I'll go through and tag some/all of the old dev docs issues so it's clear to people that we (mostly me) make plenty of mistakes.

@saivann

saivann Dec 12, 2014

Contributor

Ah, makes sense!

@saivann saivann commented on the diff Dec 12, 2014

View full changes
_includes/ref_intro.md
@@ -23,3 +24,43 @@ 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
@saivann

saivann Dec 12, 2014

Contributor

@harding Maybe "This document is not a specification"?

@harding

harding Dec 12, 2014

Contributor

Having a clear subject would be better English, but I think the longer version lacks the force of succinct subhead that starts with a negative. The subject becomes clear in the first words of the following paragraph: "The Bitcoin.org Developer Documentation..."

In any case, I don't have strong feelings here, so let me know if you want it changed.

@saivann

saivann Dec 13, 2014

Contributor

@harding Ok let's keep it as it is.
@saivann
Contributor

saivann commented Dec 12, 2014

@harding As far as I'm concerned, LGTM, thanks!
@harding
Contributor

harding commented Dec 13, 2014

@saivann thanks for your review! I think all feedback has been addressed: commit de7d371 changes the "majority" phrasing, I tagged all the old dev docs issues so the past issues link demonstrates the doc's fallibility, and opened pull #680 to update the disclaimer. Thanks again!

harding added some commits Dec 12, 2014

@harding
Dev Docs: "Not A Specification" 
Make explicit that the docs are not a specification and never will be.
8f0a80a
@harding
Dev Docs: Remove Majority Mentions In Not A Spec (thanks saivann)
f08b3e1
@harding
Dev Docs: Add Subhead-Links To "Not A Spec" Subsection
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
82f00e8
@harding
Contributor

harding commented Dec 16, 2014

Rebased and added the new subhead links to the Not A Specification subsection.

In the absence of critical feedback, I'll merge this around 13:00 UTC Thursday (48 hours from now). Additional reviews, even after the merge, are always appreciated.

@harding harding merged commit 82f00e8 into bitcoin-dot-org:master Dec 19, 2014

harding added a commit that referenced this pull request Dec 19, 2014

@harding
Merge pull #679: Dev Docs: "Not A Specification"
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
8da411b

@harding harding deleted the harding:nospec branch Feb 25, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment