Bitcoin Forum

Bitcoin => Development & Technical Discussion => Topic started by: blockgenesis on March 12, 2014, 01:40:48 AM



Title: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 12, 2014, 01:40:48 AM
Update: Developer documentation has been merged on bitcoin.org:
https://bitcoin.org/en/developer-documentation

--

The goals of this project is to improve access to good quality documentation for developers.

A lot of useful information is spread accross wiki pages, BIPS GitHub pages and BitcoinTalk threads. It would be nice to gather all this information in a single place with a consistent structure or a set of pages with a single table of content. A good "API Reference" page with code snippets would be useful too.

Good writers are needed to make this project happen. If you can help with this project, please PM me or comment on this thread. Some of this work can be paid work as the Foundation is providing a 2000$ monthly bounty ( some of it is already assigned to server and translation expenses ).

Work is already ongoing but needs more contributors to be completed. Not just writers, actually a lot of work will be to review, discuss, edit and organize all of this information.

Live preview

You can preview current work in progress here:
(Merged)

General Discussions

You can join general discussions on this Google group:
https://groups.google.com/forum/#!forum/bitcoin-documentation (https://groups.google.com/forum/#!forum/bitcoin-documentation)

Style Guide

General writing guidelines are discussed and edited here:
https://github.com/bitcoin/bitcoin.org/wiki/Documentation-Style-Guide


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: freedomno1 on March 12, 2014, 01:57:21 AM
I will probably leave this to more technical hands but I might be able to find some good points here and there so reporting in


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 12, 2014, 02:18:39 AM
I will probably leave this to more technical hands but I might be able to find some good points here and there so reporting in

PM'd, thanks!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on March 12, 2014, 06:43:39 AM
Right now there are two simple (but not necessarily easy!) ways to get started:

1.  Dip your toes in the water: work with Blockgenesis to refine the text we already have about the block chain. Blockgenesis has proposed a number of improvements (some small, some larger) and we need a writer/editor to implement those improvements.

2.  Jump into the deep end: agree to write a section of the outline Blockgenesis posted to above. The Block Chain section is written and I'm working on the Transaction section, but all the other sections are unclaimed. Just tell us what section you want and give us a rough idea about how long it will take you.

You can, of course, think up an option #3 and do that

Blockgenesis is currently co-ordinating everything, so let him know what you want to do and he'll give you access to the resources we're currently using.

-Dave (author of the block chain section in the OP link)


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Cyrus on March 12, 2014, 07:02:38 AM
Interested as well. I'm also in the process of translating bitcoin.org on transifex.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Mike Hearn on March 12, 2014, 09:38:09 AM
We definitely need a section on the payment protocol, which merges together all the BIPs and best practices into a living document. BIPs are great but they are written as "delta to previous behaviour" which can make figuring out the systems final state harder than it should be.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 12, 2014, 05:32:59 PM
We definitely need a section on the payment protocol, which merges together all the BIPs and best practices into a living document. BIPs are great but they are written as "delta to previous behaviour" which can make figuring out the systems final state harder than it should be.

Yup, I called this subsection "Payment requests". Just let me know if you feel anything is missing (or isn't relevant enough to be mentionned).

I just updated the initial thread to provide clearer procedures and instructions for anyone to take part in discussions, submit work and see assigned tasks.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Mike Hearn on March 13, 2014, 12:00:01 PM
Awesome! Let's go! :)


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Farghaly on March 13, 2014, 02:03:05 PM
I can translate into Arabic, if you need help ?


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 13, 2014, 04:15:34 PM
I can translate into Arabic, if you need help ?

You can refer to this thread for translations:
https://bitcointalk.org/index.php?topic=349633.0

Arabic translations indeed really need to be updated. Your help is more than welcome!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on March 17, 2014, 03:23:40 AM
Hi,

I'm currently writing about OP_CHECKSIG for the dev guide and I could use a quick hint from someone more knowledgeable about the SIGHASH_NONE|SIGHASH_ANYONECANPAY hash type:

What prevents peers (relayers) and miners from extracting all inputs signed with SIGHASH_NONE|SIGHASH_ANYONECANPAY from a transaction and using those inputs to create new transactions that pay themselves?

I'm confused because, on one hand, bitcoinj's payment channels seem to use SH_N|SH_ACP, (https://code.google.com/p/bitcoinj/source/browse/core/src/paymentchannel.proto) so I suspect Mike thinks it's secure, but on the other hand, I don't see how it could be based on the explanation of SH_N|SH_ACP on the wiki, (https://en.bitcoin.it/wiki/OP_CHECKSIG#Procedure_for_Hashtype_SIGHASH_ANYONECANPAY) which I understand to say:

* SH_NONE prevents signing of any outputs by the current input.

* SH_ANYONECANPAY prevents signing of any input except the current input

The combined effect being a valid input which can extracted and spent to an arbitrary script.

Any help will be appreciated,

-Dave


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Mike Hearn on March 17, 2014, 12:41:46 PM
At that stage of the protocol the signature being returned is signing for a CHECKMULTISIG output. The signature covers the outpoints, so you can't take it and apply it to any arbitrary coin (besides the keys are meant to not be reused, even though they are in the current code). The other signature for the multisig output is required and that covers the outputs.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on March 17, 2014, 01:44:18 PM
Mike:

Thank you for your answer.

I think I confused the issue by trying to generalize it and tie it into bitcoinj. Looking at a particular transaction with the form:

Code:
Input0|Input1||Output0

And...

*   Input0 is signed SIGHASH_NONE|SIGHASH_ANYONECANPAY (prevout script was pay-to-pubkey-hash)

*   Input1 is signed SIGHASH_ALL (prevout script was pay-to-pubkey-hash)

And...

*   The transaction is transmitted directly to a single miner who doesn't relay it

Question: Is it true that the miner can remove Input1 and Output0, add a new Output0, and mine the modified transaction?

---

Your answer did point out something I haven't seen documented elsewhere, so I want to make sure I understand correctly before documenting it myself:

Question: Is it true that each signature in a multisig scriptSig can use a different hash type?

Thank you again for your help! -Dave


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Mike Hearn on March 17, 2014, 07:17:22 PM
Question: Is it true that the miner can remove Input1 and Output0, add a new Output0, and mine the modified transaction?

Yes.

Quote
Question: Is it true that each signature in a multisig scriptSig can use a different hash type?

Yes.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on March 17, 2014, 07:20:01 PM
Thanks!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: genjix on March 17, 2014, 07:57:06 PM
Please specify a license for contributors. I recommend the GNU Free Documentation License.
http://www.gnu.org/copyleft/fdl.html


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 17, 2014, 08:08:59 PM
Please specify a license for contributors. I recommend the GNU Free Documentation License.
http://www.gnu.org/copyleft/fdl.html

The content on bitcoin.org is already under MIT (see the copyright notice at the bottom), which is a very permissive license (AFAIK, I'm no expert with licensing).


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: genjix on March 18, 2014, 04:16:31 PM
This file needs updating:
https://github.com/saivann/bitcoin.org/blob/dev/COPYING


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: felipelalli on March 18, 2014, 09:40:40 PM
We need a new wiki. New users can't edit it anymore and the page is very deprecated yet.

Please follow http://www.reddit.com/r/Bitcoin/comments/20b926/its_time_to_have_a_new_wiki/

@mesamunefire did it: http://thebitcoinwiki.com/index.php?title=Main_Page

But I think the community need more proof he can maintain that for a while.

 ???


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 21, 2014, 01:35:06 AM
Latest update: The first draft for the Transaction subsection is there:

(Merged)

Reviews are appreciated (only errors, omissions, confusions, and other issues at this point, writing style improvements can be done later ).


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: MarcoTC on March 27, 2014, 12:14:29 AM
Thank you for this. (where is the donation address at the bottom of the page?)
Unfortunately, I'm still catching up so I'm afraid I cannot add much to this project yet.

Until now I found that documentation is all over the place and I honestly have no idea if I'm looking at recent or outdated specs. So hopefully, this will be the place where things stay updated.

Few suggestions:

- For new developers, maybe it makes sense to have a bit more general information. For example, using bitcoin-cli, RPC or using bitcoind as border router.
- Would it be an idea to have 'user contributed notes' under each section?


But thanks again. I think it's a great initiative.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 27, 2014, 12:25:24 AM
Unfortunately, I'm still catching up so I'm afraid I cannot add much to this project yet.

Actually, reviews would be very useful at this point. If you can spot any confusing text, inaccuracies, typos, etc, please make a pull req or report them as an issue. That'll be very much appreciated.

Few suggestions:

- For new developers, maybe it makes sense to have a bit more general information. For example, using bitcoin-cli, RPC or using bitcoind as border router.
- Would it be an idea to have 'user contributed notes' under each section?

Thanks! Actually if you want to work on the API reference page, that should probably be it. As for the "user contributed notes", can you further explain your idea?


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: MarcoTC on March 27, 2014, 01:08:57 AM

Thanks! Actually if you want to work on the API reference page, that should probably be it. As for the "user contributed notes", can you further explain your idea?

As for working on the API reference page, I wish I could. Hopefully I have enough knowledge to share after I learned more and I will certainly try to help when I'm at that point.

'User contributed notes' are user comments underneath each section.
Basically, where users can submit section related remarks, pitfalls, example code snippets etc. (that maybe can be voted up, down or away).


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Mike Hearn on March 27, 2014, 12:01:52 PM
The website is purely static and for security reasons I think it should stay that way. If there is a third party commenting platform that lets us just drop something in via Javascript, I think that'd be OK but not if we need to run some kind of php/ruby thing on the bitcoin.org server itself.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on March 27, 2014, 01:23:48 PM
The website is purely static and for security reasons I think it should stay that way. If there is a third party commenting platform that lets us just drop something in via Javascript, I think that'd be OK but not if we need to run some kind of php/ruby thing on the bitcoin.org server itself.

Agreed, no server-side scripting for now.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on March 31, 2014, 07:35:44 PM
Edit:  After reading through the Bitcoin Core source code for an embarrassingly long time, I figured out that this paragraph from BIP70,

Quote
signature: digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.

means to do this:

Code:
request.signature = ""

before doing this:

Code:
request.signature = sign(priv_key, request.SerializeToString(), "sha256")

Thanks to everyone who read my previous post.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on April 02, 2014, 02:08:23 PM
Hi,

The payment processing section (including BIP70 payment requests) has been added to the devguide.  Comments and suggestions are welcome on the pull request. (https://github.com/saivann/bitcoin.org/pull/38)

(Please comment there even though the pull request is closed.  Every comment posted will be read and replied to.)

Thanks to Saïvann's late-night efforts, you can read the new section in nicely-formatted HTML on the demo site. (http://bitcoindev.us.to/en/developer-guide#payment-processing)

General questions or comments should be sent here, the mailing list (https://groups.google.com/forum/?hl=en#!forum/bitcoin-documentation), or submitted as an issue. (https://github.com/saivann/bitcoin.org/issues)

Thanks!, -Dave


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on April 12, 2014, 07:59:38 PM
Hi,

We could use a little advice about what's relevant to wallet authors when it comes to choosing which inputs to select for making a new payment.  We described three options:

* A merge avoidance algorithm makes it harder for outsiders looking at block chain data to figure out how many satoshis the receiver has earned, spent, and saved.

* A last-in-first-out (LIFO) algorithm spends newly acquired satoshis while there's still double spend risk, possibly pushing that risk on to others. This can be good for the receiver's balance sheet but possibly bad for their reputation.

* A first-in-first-out (FIFO) algorithm spends the oldest satoshis first, which can help ensure that the receiver's payments always confirm

We were thinking about cutting out FIFO because it doesn't seem very useful (except for being reliable and easy to implement).  We were further discussing whether we should cut out LIFO---which might be useful for some applications---in order to emphesize the privacy benefits of merge avoidance.

However, none of us writers/editors have any practical experience here, so we would appreciate some developer feedback about what you need to know.  Here's a direct link to the input-selection section (http://bitcoindev.us.to/en/developer-guide#disbursing-income-limiting-forex-risk) and our GitHub discussion of the issue. (https://github.com/saivann/bitcoin.org/pull/52)

A quick trace of Electrum's source code (which I happend to have handy) made it seem like it used FIFO.

Thanks, -Dave


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: doof on April 25, 2014, 03:47:09 AM
Can some please explain the procedure of signing a transaction with multiple inputs?


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: BCB on May 11, 2014, 02:48:53 AM
I've only just skimmed the new docs but I'm impressed.  Great job.  I'm looking forward to reading it more closely.

Thank you.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on May 11, 2014, 01:40:08 PM
Notes about where to contribute to the current effort from the bitcoin-development mailing list:

Quote from: blockgenesis
A new "Developer Documentation" section should be soon merged on
bitcoin.org .

Live Preview:
http://bitcoindev.us.to/en/developer-documentation

GitHub Pull Request:
https://github.com/bitcoin/bitcoin.org/pull/393

Bitcointalk Thread:
https://bitcointalk.org/index.php?topic=511876.0

We've worked hard to come up with good quality documentation and general
feedback has been positive. Reviews from experienced Bitcoin developers
would now be much appreciated. You are cordially invited to help
proofread the documentation so it can be published soon!

*Please avoid commenting on the mailing list* to not spam everyone. See
the pull request for instructions. Comments should go on the pull
request or bitcoin-documentation mailing list
https://groups.google.com/forum/#!forum/bitcoin-documentation .


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on May 19, 2014, 10:23:22 PM
A quick update on the project:

More reviews and feedback on the pull request are very welcome so we can get this merged:
https://github.com/bitcoin/bitcoin.org/pull/393

This pull request will be merged on May 24th and hopefully will be accurate as much as possible. Reporting any inaccuracy / mistake on the pull request is very appreciated.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: doof on May 23, 2014, 05:47:57 AM
Can some please explain the procedure of signing a transaction with multiple inputs?

Now that I have figured it out with help of bitcointalk members, i might add this myself.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: super3 on May 24, 2014, 07:13:32 PM
A quick update on the project:

More reviews and feedback on the pull request are very welcome so we can get this merged:
https://github.com/bitcoin/bitcoin.org/pull/393

This pull request will be merged on May 24th and hopefully will be accurate as much as possible. Reporting any inaccuracy / mistake on the pull request is very appreciated.
This is a grade A piece of work. Donated 0.1 BTC to your address.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: piotr_n on May 24, 2014, 07:34:49 PM
Fascinating lecture.
But you cannot seriously think that this is more useful for a dev than the old wiki.
Or can you?
Well, IMHO it isn't - devs need tables and short explanations, not epic descriptions.
It looks good to be released as a book, though.

Not saying that this is a bad piece - only that it is too long to read, as for dev purposes.
Bitcoin isn't that complicated, nor we seek adventures in its documentation.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on May 24, 2014, 07:44:54 PM
Hi, piortr_n.

Did you checkout both the guide and the reference pages?  The guide is aimed at new developers who need to learn how Bitcoin works.  The reference is aimed at the developers who know how the general system works but need, as you say, tables and short explanations (which we've put all on one page for easy in-browser Ctrl-f searching).

  • Guide: https://bitcoin.org/en/developer-guide
  • Reference: https://bitcoin.org/en/developer-reference

Both are linked to from the main page, which also links to other useful resources: https://bitcoin.org/en/developer-documentation

We'll be adding more content over the next few monhs, so check back often!  Thanks!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: piotr_n on May 24, 2014, 08:01:16 PM
I think I did check everything and really comparing both of your pages, to these two:
https://en.bitcoin.it/wiki/Protocol_specification
https://en.bitcoin.it/wiki/Script
.. I would not envy a guy who has to build a bitcoin software, basing only on your spec.

But OK, I understand that it isn't complete.

Still, if I may add, most of all you need a nice & clean table with all the network messages linking to their descriptions (with sub-tables describing the payload of each type).
And the same for the script - I don't see a table with script opcodes in your spec.
That's the two references I've used the most - nothing else matters that much.

You can have some more epic descriptions, but they should rather be there as an additional help.
So only if anyone doesn't understand what an opcode does (by its name or short desc), he clicks a link and goes there.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on May 24, 2014, 08:27:50 PM
piotr_n:

Our audience description (https://github.com/bitcoin/bitcoin.org/wiki/Documentation-Style-Guide#audience-description) says that we're focusing on application developers, which (in my mind) means that we prioritize writing documentation for developers who will use libraries or Bitcoin Core RPCs for the underlying network communication.

Once we've covered the topics application developers need to know, I'm happy to move on to topics library developers or core re-implementors need to know.

As for opcodes, we describe all the opcodes used in standard transactions here: https://bitcoin.org/en/developer-reference#op-codes

As for cross-reference linking, we use it extensively---there are over 2,000 links in the Guide and Reference.  Just hover your mouse over a paragraph to see all of the internal links appear in blue.  You can further hover your mouse over a term to get a brief description, and then click on it to go to the full description.

We really did put a lot of work into trying to design the docs to be useful for developers at all stages, from Bitcoin neophyte to core dev.  Given more time (or more volunteers!) we'll be able to fulfill our core mission and expand the docs to cover more and more parts of Bitcoin.

Thanks for your comments!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on May 24, 2014, 08:36:04 PM
Yup, it's always good to move forward and think of new improvement. We can't have everything on v0.1 . :)

Also, I think that's a good reason why it made sense to focus on bringing new content (walkthrough and explanations) rather than duplicating existing tables on the Wiki (and link to them instead). But at some point I agree that having all this content in a single place can indeed be a useful step forward.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: piotr_n on May 24, 2014, 08:57:26 PM
OK - so it's for "applications".
Now I would have asked "what kind of applications?" if not for the fact that I already figured that you mean applications based on bitcoind's RCP API, or an API of other components that your firm is busy developing.
As an opposite to the actual (software independent) bitcoin protocol applications, as I perceive such through the proto described on the wiki.

So currently it is not a "Bitcoin Developer Reference", but rather a manual for bitcond's RPC API, right?
In such case, I have no critical comments, except maybe for the title of this doc, which I find a bit misleading, to say the least.

You ought to at least make it clear that it is a guide for a specific software API, not so much for Bitcoin as the universal bitcoin protocol.
Otherwise some more experienced devs could blame you of advertising a misleading message about what Bitcoin actually is  :)


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on May 24, 2014, 11:33:08 PM
I already figured that you mean applications based on bitcoind's RCP API, or an API of other components that your firm is busy developing.

There is no firm.  This is volunteer-written documentation for the entire Bitcoin community.  However, we do have to start somewhere---and I can't think of anywhere better to start than Bitcoin Core.

I'm sorry if I confused you.  Thanks again for your comments!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: piotr_n on May 25, 2014, 03:39:41 PM
Sorry, it's said in OP that the foundation might pay $2000/month for this project, so it made me thinking that they were driving this spec.

Anyway, I believe it is important to have it clearly distinguished where an actual protocol ends and where a specific software implementation starts.
The doc, although a nice piece of work, unfortunately mixes it all up.

To be more specific.
Lets go to the section "P2P Network / Peer Discovery" - what would I, a developer, expect to find there?
I would expect to find a technical information about how the peers discover each other in the p2p network.
But what I find is a description of what command line switches I can use when launching "Bitcoin Core" (that's a new name for me, BTW - it was always bitcond or bitcoin-qt).
Then somewhere at the end, there is finally a mention of the actual protocol, but pretty laconic and also quite useless (at least ATM), because it still requires you to go to the wiki to learn about the actual format of the payload of the addr message.
Then you have a few sections where you talk strictly about the p2p protocol... until a reader reaches the "Misbehaving Nodes", where his lecture suddenly gets switched back to bitcoind's user manual, and that's without even any indication of the fact.
I think it's pretty confusing. I mean, it doesn't confuse me (you don't need to be sorry), but it will definitely confuse people who read it to study bitcoin.

There is a huge difference between a bitcoin protocol and a specific implementation of a software, but I don't see the doc being even aware of this fact.
If you want to make this spec right, I would advise to try not mixing up these two things.
A reader should be aware all the time whether he is reading about a specific software implementation or about a protocol.
Moreover, it is also important to distinguishing the protocol's must-have hard rules (blockchain validation) and the protocol's may-have soft rules (different address types, the payment protocol, bloom filters, etc). And of course, the command line switches are neither of the two - they are the third kind, a user manual kind.

To wrap up, it is a really nice literature, you obviously put a lot of work into it and it has a potential to become a useful dev spec, but..
IMHO you should restructure it, because now it mixes up things from completely different domains, without mentioning it to the reader. That is not good for a developer's guide / reference.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on May 25, 2014, 03:52:24 PM
Sorry, it's said in OP that the foundation might pay $2000/month for this project, so it made me thinking that they were driving this spec.

Beside supporting the project, the Foundation is uninvolved with decision-making. Most of this money was allocated to translations.

Anyway, I believe it is important to have it clearly distinguished where an actual protocol ends and where a specific software implementation starts.

Agreed, I think we can continue to move toward this goal, although it will never be perfect as the distinction isn't always clear in reality either (Bitcoin Core being "the specification" right now until we possibly have multiple full nodes implementations in the future).


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: piotr_n on May 25, 2014, 04:09:33 PM
although it will never be perfect as the distinction isn't always clear in reality either (Bitcoin Core being "the specification" right now until we possibly have multiple full nodes implementations in the future).
Indeed.
Certainly you cannot say whether e.g. the fact that a banned peer gets un-banned after 24h - is a protocol rule, or a specific implementation.
In fact, entire domains like the "misbehaving nodes" concept or "standard transactions" are implementation specific.
Of course it is important to have it documented, because the bitcoin core handles now like 99,99% of the network, but when developing your own bitcoin node nobody can force you to follow these specific concepts and a development spec should be clear about it.
At the other hand developing your own node you definitely need to follow the p2p spec (at least for the commands you use), and most of all: the blockchain protocol - that's the very core of bitcoin, and still not quite documented.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: super3 on May 25, 2014, 06:02:11 PM
Can someone post a list of the authors to this guide and their bitcoin addresses here?


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on May 25, 2014, 07:12:16 PM
super3:

Greg Sanders and myself (Dave Harding) wrote almost all of the original text. The in-text illustrations were all done by me, I think. Saïvann Carignan (blockgenesis) was managing editor, integrated the text into the website (along with icon development), and generally did the many small necessary things to keep the project on track and productive. I'd call us three the current core docs team (but more people are welcome!).

Mike Hearn brought most of us together, provided a large number of invaluable early reviews, and more ongoing feedback to the degree his busy schedule allowed.  Knowing we had the explicit support of at least one core dev was highly motivating, and I think we're all deeply appreciative that Mike was willing to lend his time to our endeavor.

Tom Geller provided line-level editing of the first-written section of the guide, the Block Chain section, as well as creating the style guide we continue to follow.

Chris Beams has been continually providing reviews, feedback, testing, and suggestions both on the text and the website presentation.

Quite a few other people have contributed, although in ways that are harder to track. For example, Greg and myself used the Bitcoin Wiki extensively for research, and the authors of those articles deserve a huge thanks. We're also incredibly grateful to everyone who reviewed parts of our text for accuracy---even if they didn't find any mistakes.

I hope I haven't forgotten anyone.

As for Bitcoin addresses, Saïvann (blockgenesis) received some docs thank-you donations and has already made arrangements to split them between himself, Greg, and myself once they stop coming in. He's been receiving those donations to the address in his sig, 18XXXQs1vAQGBAZbXKA322r9Zy1nZac2H4.  If you send a tip because of the docs, you really should mention it to him that it was for the docs.

However, speaking only for myself, I think the best contributions we can receive are additional reviews for accuracy and help spreading the word about these docs.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: super3 on May 25, 2014, 07:23:54 PM
super3:

Greg Sanders and myself (Dave Harding) wrote almost all of the original text. The in-text illustrations were all done by me, I think. Saïvann Carignan (blockgenesis) was managing editor, integrated the text into the website (along with icon development), and generally did the many small necessary things to keep the project on track and productive. I'd call us three the current core docs team (but more people are welcome!).

Mike Hearn brought most of us together, provided a large number of invaluable early reviews, and more ongoing feedback to the degree his busy schedule allowed.  Knowing we had the explicit support of at least one core dev was highly motivating, and I think we're all deeply appreciative that Mike was willing to lend his time to our endeavor.

Tom Geller provided line-level editing of the first-written section of the guide, the Block Chain section, as well as creating the style guide we continue to follow.

Chris Beams has been continually providing reviews, feedback, testing, and suggestions both on the text and the website presentation.

Quite a few other people have contributed, although in ways that are harder to track. For example, Greg and myself used the Bitcoin Wiki extensively for research, and the authors of those articles deserve a huge thanks. We're also incredibly grateful to everyone who reviewed parts of our text for accuracy---even if they didn't find any mistakes.

I hope I haven't forgotten anyone.

As for Bitcoin addresses, Saïvann (blockgenesis) received some docs thank-you donations and has already made arrangements to split them between himself, Greg, and myself once they stop coming in. He's been receiving those donations to the address in his sig, 18XXXQs1vAQGBAZbXKA322r9Zy1nZac2H4.  If you send a tip because of the docs, you really should mention it to him that it was for the docs.

However, speaking only for myself, I think the best contributions we can receive are additional reviews for accuracy and help spreading the word about these docs.
Ok I sent some BTC to that address earlier. I'll probably send some more at another time. Thanks for compiling an authors list. Good documentation was something that we have been missing for a while. Glad to finally have something.

I just finished reading through it today. I've been making minor contributions to Bitcoin core since about mid 2013, trying to learn about as much about the protocol as I could. This has really leapfrogged my understanding, and I really appreciate it.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on May 26, 2014, 04:09:58 AM
However, speaking only for myself, I think the best contributions we can receive are additional reviews for accuracy and help spreading the word about these docs.

+1, but many thanks to the people who gave some generous tips!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: Summer,69 on June 02, 2014, 11:47:58 AM
how much I still need to learn in order to begin to understand what is at stake!


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: instagibbs on June 02, 2014, 03:11:27 PM
although it will never be perfect as the distinction isn't always clear in reality either (Bitcoin Core being "the specification" right now until we possibly have multiple full nodes implementations in the future).
Indeed.
Certainly you cannot say whether e.g. the fact that a banned peer gets un-banned after 24h - is a protocol rule, or a specific implementation.
In fact, entire domains like the "misbehaving nodes" concept or "standard transactions" are implementation specific.
Of course it is important to have it documented, because the bitcoin core handles now like 99,99% of the network, but when developing your own bitcoin node nobody can force you to follow these specific concepts and a development spec should be clear about it.
At the other hand developing your own node you definitely need to follow the p2p spec (at least for the commands you use), and most of all: the blockchain protocol - that's the very core of bitcoin, and still not quite documented.

Any place that doesn't mention that we are talking about Bitcoin Core vs protocol, please submit an issue or pull request. Much appreciated!

Peer discovery doesn't have to be done any particular way, protocol-wise, but in today's environment we deal with Bitcoin Core. As long as we stress that, I think it's ok. I'd be a little baffled if someone writing a complete alternative full implementation didn't understand the implications.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 10:48:18 AM
Sorry, it's said in OP that the foundation might pay $2000/month for this project, so it made me thinking that they were driving this spec.

Beside supporting the project, the Foundation is uninvolved with decision-making. Most of this money was allocated to translations.


Many of the same old Bitcoin Foundation members are making the decisions.  They are using some interesting criteria about what gets posted.  I ran across some confusion over the settings in .conf and I tried to have the Wiki entry updated and merged with the current developers guide.  I was met with all kinds of resistance and told that Bitcoin Core should not even be on the site!  Of course Satoshi created the site just for that purpose.

I also tried to get my Bitcoin.me video (https://www.youtube.com/watch?v=t4UYpbRO8nw) placed alongside the other third party vids on the press page.  The guy who runs Bitcoin.org said he liked the video wouldn't add it due to my "attitude."  I have been complaining that the site was hijacked by a small group who shut most people out from these decisions.

Just what we need in Bitcoin, a small group exercising centralized control who acts as the "attitude police" to try to force people to go along with their ideas.    


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: instagibbs on October 01, 2014, 01:13:31 PM


Many of the same old Bitcoin Foundation members are making the decisions.  They are using some interesting criteria about what gets posted.  I ran across some confusion over the settings in .conf and I tried to have the Wiki entry updated and merged with the current developers guide.  I was met with all kinds of resistance and told that Bitcoin Core should not even be on the site!  

The primary guide is indeed *not* about Bitcoin Core config files, but trying to best describe the protocol(trying to avoid the debate about whether p2p networking is a part of the protocol or not. Config files surely aren't).

The guidelines for what is included were designed in the open, and everyone was encouraged to contribute. The fact is that only a few people ended up writing most of it because only a few volunteered.

If you want .config stuff included you're going to have to argue your position on this and not just cry about the Bitcoin Foundation.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on October 01, 2014, 01:34:58 PM
Don't feed the trolls.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 01:46:31 PM


Many of the same old Bitcoin Foundation members are making the decisions.  They are using some interesting criteria about what gets posted.  I ran across some confusion over the settings in .conf and I tried to have the Wiki entry updated and merged with the current developers guide.  I was met with all kinds of resistance and told that Bitcoin Core should not even be on the site!  

The primary guide is indeed *not* about Bitcoin Core config files, but trying to best describe the protocol(trying to avoid the debate about whether p2p networking is a part of the protocol or not. Config files surely aren't).

The guidelines for what is included were designed in the open, and everyone was encouraged to contribute. The fact is that only a few people ended up writing most of it because only a few volunteered.

If you want .config stuff included you're going to have to argue your position on this and not just cry about the Bitcoin Foundation.

Yes, the site was hijacked from its original purpose which was the site for the Bitcoin Core project.  Because it has good SEO it is now being used for other purposes.

as for the config file info the commands are already there in the developers guide for the most part.  The config file information for end users is on the wiki but it is outdated.  I wanted to move the wiki entry, update it, and combine it with the information that is already in the developers guide because it all goes together and bitcoin.org is kept up to date as far as the command line items.  Because the Wiki is outdated and information is now being posted at bitcoin.org you have 2 sets of (sometimes) conflicting information.  I suggested the stuff be updated and moved to bitcoin.org and I was ready to do it.  then Luke-Jr started with a bunch of nonsense and started claiming the site was not for Bitcoin Core and that info should be moved off the site.

After that argument Luke-Jr and Saivann told me my video was good but it was not going to be added because of my "attitude."  They want to control what I say and do on other issues in exchange for posting the video I developed.  the content should be posted on merit, not on deals struck with those who got the site from Satoshi. Of course whoever owns the site can do what they want with it but I object to the claim that it is "community" developed.

Basically, they are pushing people away so they can control things for their own purposes.  I have seen several people in the past who wanted to participate but they became disenchanted with the way these issues are being handled.  Now you have a tiny group of people running the entire site and dictating its content.  



  


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 01:56:00 PM
Don't feed the trolls.

The bitcoin.org sock puppet speaks.  This is the kind of childish reply you get when you try to do something.

I guess I "trolled" FinCEN when I got the Bitcoin mining decision:
http://www.coindesk.com/fincen-bitcoin-miners-need-not-register-money-transmitters/

I guess I am trolling the community when I had the video made at my expense:
https://www.youtube.com/watch?v=t4UYpbRO8nw

I just hang out and troll all day.






Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: SlipperySlope on October 01, 2014, 04:12:26 PM
Don't feed the trolls.

Thanks to you and to the foundation for the Developer Guide.

Most of the conversation is on-topic. Not trollish behavior I believe. Crowdsourced projects need to air their issues, while achieving consensus on their policies.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 05:23:04 PM
Don't feed the trolls.

Thanks to you and to the foundation for the Developer Guide.

Most of the conversation is on-topic. Not trollish behavior I believe. Crowdsourced projects need to air their issues, while achieving consensus on their policies.

Thanks.  My point is to clear up the confusion.  I provide support to new users who have no idea what is going on and they spend all day communicating with experts so issues are seen differently.  What I see happening is that people are referencing outdated or incomplete Wiki entries and it is creating confusion.  Right now census means 2 or 3 insiders decide everything.  Generally the discussion are abruptly cut off in the middle of a discussion once the 2 or 3 insiders comment and make their decision.   If you argue you are a "troll " who is "wasting their time."

for instance, look at the wiki discussion of Bitcoin addresses:

https://en.bitcoin.it/wiki/Address#Address_balances

several of these statements are confusing and they appear to contain editorial comments mixed in with fact similar to incorrect things always Luke-Jr says.  While you can't read the balance directly off the blockchain it can be calculated contrary to the way the Wiki describes it.  The discussion appears to be associated with luke-Jr's dislike of Blockchain.info so he makes all kinds of statements about Bitcoin addresses to try to make Blockchain.info look bad.

As for address reuse Bitcoin was designed so you can use different addresses for each transactions but some users have a specific purpose for address reuse.  People who claim Bitcoin was "meant" to be used one way or another are really inserting editorial comments and not fact and they treat Bitcoin like a religion.  It is a tool that can be used many different ways and not reusing address may be advisable under some circumstances but you can't make blanket statements like that.

If changes are made to the Wiki the same 2 or 3 people who run both the Wiki and Bitcoin.org deny any changes and keep their personal preference which, in this case, is wrong.  An argument ensued last week involving someone who pointed to the Wiki Bitcoin address definition and took it as fact.  Then you had people pointing to Bitcoin.org and claiming something different based on that description which is completely different.  

Also, several users are interested in changing their bitcoin.conf settings which is why I raised that issue.  The developers often raise the issue that users can change their settings.  the Wiki entry is outdated.  Now the developers (at least Gregory Maxwell) says having users edit the conf file will cause to many tech support issues and they say users should be using command line.  Many users never use command line but they may want to change their setting.  For instance, they may wish to connect only to a specific node to prevent their IP from being captured on sites such as blockchain.info.

I am no longer allowed to discuss this on Github because the one person who makes the decisions banned me from the entire site.  It is apparently the same person holding the sock puppet account who just labeled me a "troll"


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: blockgenesis on October 01, 2014, 05:43:09 PM
I think Bitcoin Core configuration files is OT here, this thread is for developer documentation, not user documentation.

This said, as (repeatedly) stated, no permission is required to update the wiki if it is oudated. If someone wants to do the work of duplicating the content and keeping it up to date on bitcoin.org, all this person have to do is to do all the work and convince other contributors it's a good idea, like any other change.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 06:07:27 PM
I think Bitcoin Core configuration files is OT here, this thread is for developer documentation, not user documentation.

This said, as (repeatedly) stated, no permission is required to update the wiki if it is oudated. If someone wants to do the work of duplicating the content and keeping it up to date on bitcoin.org, all this person have to do is to do all the work and convince other contributors it's a good idea, like any other change.

The developers guide already lists the command line arguments.  The conf file is a subset of those commands.  Bitcoin.org is also doing a page on running your own node (see https://github.com/bitcoin/bitcoin.org/issues/410).  The page about running your own node was suggested by an insider and  approved by you and Garzik without any argument about posting user documentation.  You are going to need the conf file explanation on that page so my issue was 100% on topic as I see it.  I would suggest putting in with the command line arguments in the developer's guide and linking to it from the "Running your own node page."  maybe you can explain more why this "off-topic."

All the information is already within, or will be within, bitcoin.org and there is no purpose in trying to change the Wiki to make a second copy of the same information.  Especially if Luke Jr. is going to come in and deny/change the edits so I would not waste my time trying to do that.  Many people have stopped editing the wiki due to those types of complaints.

The "other contributors" are mostly the 2 or 3 people who go around calling anyone who disagrees with them "trolls."  There is no viable way to reach any sort of community consensus under the current system.  You have already told me the only reason you denied posting the video I had made was because of my "attitude" which is not a legitimate reason.  I am starting to see other similar questions being raised, such as which wallet programs get listed, so I am glad this is bringing everything out into the open.



Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: harding on October 01, 2014, 07:36:41 PM
The developers guide already lists the command line arguments.  The conf file is a subset of those commands.

Incorrect.  The developers reference describes Remote Procedure Calls (RPCs) which have nothing to do with the configuration files.

Bitcoin.org is also doing a page on running your own node (see https://github.com/bitcoin/bitcoin.org/issues/410).  ... You are going to need the conf file explanation on that page

Incorrect. I opened the issue proposing that page based on a bitcoin-devel mailing list discussion and, as the issue says, I'm delaying writing that page until there's a setup-free package which allows Bitcoin Core to run as a background service---that means no config file editing will be required.

All the information is already within, or will be within, bitcoin.org and there is no purpose in trying to change the Wiki to make a second copy of the same information.

Incorrect, as described above.

> if Luke Jr. is going to come in and deny/change the edits so I would not waste my time trying to do that.

Scurrilous.  Luke-Jr is the one who suggested you update the Wiki, so he's unlikely to reject a quality contribution.

You have already told me the only reason you denied posting the video I had made was because of my "attitude" which is not a legitimate reason.

I disagree. The video promotes your website (Bitcoin.me) and so your behavior is highly relevant. Based on the calumnious statements you've made in the pull request, issues, email correspondence, and this thread, I would recommend people stay away from you and your website.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 07:52:17 PM
The developers guide already lists the command line arguments.  The conf file is a subset of those commands.

Incorrect.  The developers reference describes Remote Procedure Calls (RPCs) which have nothing to do with the configuration files.

Bitcoin.org is also doing a page on running your own node (see https://github.com/bitcoin/bitcoin.org/issues/410).  ... You are going to need the conf file explanation on that page

Incorrect. I opened the issue proposing that page based on a bitcoin-devel mailing list discussion and, as the issue says, I'm delaying writing that page until there's a setup-free package which allows Bitcoin Core to run as a background service---that means no config file editing will be required.

All the information is already within, or will be within, bitcoin.org and there is no purpose in trying to change the Wiki to make a second copy of the same information.

Incorrect, as described above.

> if Luke Jr. is going to come in and deny/change the edits so I would not waste my time trying to do that.

Scurrilous.  Luke-Jr is the one who suggested you update the Wiki, so he's unlikely to reject a quality contribution.

You have already told me the only reason you denied posting the video I had made was because of my "attitude" which is not a legitimate reason.

I disagree. The video promotes your website (Bitcoin.me) and so your behavior is highly relevant. Based on the calumnious statements you've made in the pull request, issues, email correspondence, and this thread, I would recommend people stay away from you and your website.

These are the kind of replies you get from the insiders.  If they don't like you so they come up with arguments to leave out important documentation.  My issues really don't matter that much but they are going to be doing this stuff to Bitcoin businesses who want wallets and services listed there.

BTW - Harding is upset over miners because they write about making money and he wants no part of that ... even though that is the key incentive for which all of Bitcoin depends.  So we have the Saivann, Harding and Luke-Jr making most of the decisions about what goes up on Bitcoin.org.  It has good info but it is basically turning into a donation source for the Foundation.  Too few people have control over too much of the resources.


Title: Re: Developer Guide on bitcoin.org: writers/reviewers needed
Post by: HELP.org on October 01, 2014, 08:18:23 PM
If Harding is worried about the reputation of the people running web sites he should be concerned about the Bitcoin Foundation:

"Bitcoin’s sinister side was highlighted early on with the Silk Road arrests, not to mention Mt. Gox’s failure, Coinlab’s (largely ignored) fraudulent bankruptcy filing (http://www.plainsite.org/dockets/unc1p5dn/washington-western-bankruptcy-court/cli-holdings-inc/), and Charlie Shrem’s drug-related scandal."

http://contrariancompliance.com/2014/09/25/bitcoiners-are-repeating-forgotten-history-and-are-accordingly-doomed/

Read the Vessenes court filing here:

http://cointext.com/wp-content/uploads/2013/11/alydiancomplaint.pdf

So that stuff is OK but my video is not recommended?  This is a joke, I am done trying to help.