Developer Guide

indolering
Posts: 801
Joined: Sun Aug 18, 2013 8:26 pm
os: mac

Developer Guide

Post by indolering »

The wiki is a mess, it has very limited access/control mechanisms and we really need a Bitcoin-style developer guide that outlines the inner workings of Namecoin.

For example, I wanted to double-check my understanding of the registration process, but I had to hit IRC to figure it out. I've also had people come online asking for technical references. Most important, however, is that it would help chip away at the steep learning curve required to start making meaningful contributions.

Forking Bitcoin's developer guide would be very complex, I was thinking of just using Namecoin Core's GitHub wiki. This would allow us to restrict edits to developers who know what they are talking about.

Thoughts?
DNS is much more than a key->value datastore.

biolizard89
Posts: 2001
Joined: Tue Jun 05, 2012 6:25 am
os: linux

Re: Developer Guide

Post by biolizard89 »

indolering wrote:The wiki is a mess, it has very limited access/control mechanisms and we really need a Bitcoin-style developer guide that outlines the inner workings of Namecoin.

For example, I wanted to double-check my understanding of the registration process, but I had to hit IRC to figure it out. I've also had people come online asking for technical references. Most important, however, is that it would help chip away at the steep learning curve required to start making meaningful contributions.

Forking Bitcoin's developer guide would be very complex, I was thinking of just using Namecoin Core's GitHub wiki. This would allow us to restrict edits to developers who know what they are talking about.

Thoughts?
Jekyll is better for this. That way anyone can contribute, but an ACK from a developer is needed.
Jeremy Rand, Lead Namecoin Application Engineer
NameID: id/jeremy
DyName: Dynamic DNS update client for .bit domains.

Donations: BTC 1EcUWRa9H6ZuWPkF3BDj6k4k1vCgv41ab8 ; NMC NFqbaS7ReiQ9MBmsowwcDSmp4iDznjmEh5

indolering
Posts: 801
Joined: Sun Aug 18, 2013 8:26 pm
os: mac

Re: Developer Guide

Post by indolering »

biolizard89 wrote: Jekyll is better for this. That way anyone can contribute, but an ACK from a developer is needed.
You can submit a pull request for a wiki, but I'm open to having a developer guide repo as well.
DNS is much more than a key->value datastore.

biolizard89
Posts: 2001
Joined: Tue Jun 05, 2012 6:25 am
os: linux

Re: Developer Guide

Post by biolizard89 »

indolering wrote:
biolizard89 wrote: Jekyll is better for this. That way anyone can contribute, but an ACK from a developer is needed.
You can submit a pull request for a wiki, but I'm open to having a developer guide repo as well.
I would just make it a subdirectory (or maybe a Git Submodule) of the main Jekyll site. Easier to deal with on the server side and works just as well.
Jeremy Rand, Lead Namecoin Application Engineer
NameID: id/jeremy
DyName: Dynamic DNS update client for .bit domains.

Donations: BTC 1EcUWRa9H6ZuWPkF3BDj6k4k1vCgv41ab8 ; NMC NFqbaS7ReiQ9MBmsowwcDSmp4iDznjmEh5

indolering
Posts: 801
Joined: Sun Aug 18, 2013 8:26 pm
os: mac

Re: Developer Guide

Post by indolering »

biolizard89 wrote:
indolering wrote:
biolizard89 wrote: Jekyll is better for this. That way anyone can contribute, but an ACK from a developer is needed.
You can submit a pull request for a wiki, but I'm open to having a developer guide repo as well.
I would just make it a subdirectory (or maybe a Git Submodule) of the main Jekyll site. Easier to deal with on the server side and works just as well.
What about creating a distinct website at dev.namecoin.org? That way it could be a static Github site, removing the need to mess with the Namecoin server and proxy. We could start out with the developer guide and add API documentation (if we ever get that done).

There are drawbacks to using submodules....
DNS is much more than a key->value datastore.

indolering
Posts: 801
Joined: Sun Aug 18, 2013 8:26 pm
os: mac

Re: Developer Guide

Post by indolering »

... but we would have to use submodules or subtrees for any auto-generated API documentation. So I guess the main advantage is the ability to use Github's static site hosting.

FWIW, I was thinking we would stub out most of the documentation at first.
DNS is much more than a key->value datastore.

indolering
Posts: 801
Joined: Sun Aug 18, 2013 8:26 pm
os: mac

Re: Developer Guide

Post by indolering »

Discussion from an email correspondence with Domob:
domob wrote:Sounds like a noble project, as long as you have time to spend on that. If you have any questions, feel free to ask me.
I was going to contribute a description of how name registration works and stub out the rest. FWIW, I would be happy to spend an evening porting anything on the wiki.

There have been at least a couple of people on IRC asking for such documentation and others have added stuff to the wiki. If we create a space for these contributions, others will come along and add to it. And if we ever get funding, I would be for paying Domob to sit down and write some documentation.

The problem with the wiki is that random people have been adding proposed changes and incorrect information. Both Jeremy and I have tried to work out some sort of permission system, but Mediawiki just isn't suited for this task: the documentation explicitly states that anyone needing a permissions workflow should switch to something else. Git/Github fits with the rest of our workflow and allows for outside contributions.
domob wrote: Note, though, that I think that most of the learning curve concerns the common codebase with Bitcoin (compared to that, the Namecoin-specific changes are "relatively few"). I. e., in my opinion it would be best to look at how Bitcoin does it (I'm not aware of any documentation in that direction) and build on that. If nothing usable exists, it would be best to coordinate with Bitcoin itself to build such a guide for Bitcoin Core.
Bitcoin has a very nice developers guide and is what prompted me to start putting together a Namecoin developers guide. However, it is semi-custom and I don't think we could stay on top of the changes.

I was thinking of the Namecoin developer's guide more as a diff in that we would only document Namecoin specific deviations and point people to the Bitcoin developers guide for the rest.
DNS is much more than a key->value datastore.

cassini
Posts: 336
Joined: Sun May 26, 2013 6:36 pm

Re: Developer Guide

Post by cassini »

indolering wrote:Bitcoin has a very nice developers guide
Is it this the official version? https://bitcoin.org/en/developer-reference

indolering
Posts: 801
Joined: Sun Aug 18, 2013 8:26 pm
os: mac

Re: Developer Guide

Post by indolering »

cassini wrote:
indolering wrote:Bitcoin has a very nice developers guide
Is it this the official version? https://bitcoin.org/en/developer-reference
Yes.
DNS is much more than a key->value datastore.

domob
Posts: 1129
Joined: Mon Jun 24, 2013 11:27 am
Contact:

Re: Developer Guide

Post by domob »

cassini wrote:
indolering wrote:Bitcoin has a very nice developers guide
Is it this the official version? https://bitcoin.org/en/developer-reference
Ah cool, I didn't know about that. So you are talking about a guide to the additional APIs and name scripts? I thought it was about the actual code and internal database structure of Namecoin Core - which seems to be not the subject of the Bitcoin guide.
BTC: 1domobKsPZ5cWk2kXssD8p8ES1qffGUCm | NMC: NCdomobcmcmVdxC5yxMitojQ4tvAtv99pY
BM-GtQnWM3vcdorfqpKXsmfHQ4rVYPG5pKS
Use your Namecoin identity as OpenID: https://nameid.org/

Post Reply