RChain Architecture document revision

[dckc]

A few people, including one of the authors (@edeykholt), have noticed that the architecture document is out of date in a few places (e.g. SpecialK). Meanwhile, several groups have translated it into various languages, so they must know it pretty well. I have talked with @MParlikar about organizing an effort to update the document, and she supports the idea and says it's worth some of Mike Stay's time.

Let me know if you're interested and available to

• raise issues in the arch doc repository
• meet occasionally to discuss them
• make pull requests to fix them
• update your translation

Candidates:

• Chinese: @AbnerZheng said he's interested; others?
• Russian: @qelentium ?
• Ukranian: @irynapopova61
• Italian: @staff91 ?

cc @Jake-Gillberg

[ghost]

@dckc ok

[qelentium]

@dckc im in! :)

[dckc]

My RChain office hours might be a good time to talk about this. Saturdays 9am Chicago time. See #403 for details.

[dckc]

@AbnerZheng and I talked about this today.

I don't have rights to merge PRs, but that's OK, at least for now; we want changes to go through @pyrocto anyway.

For typos and obvious fixes, just file pull requests like #21.

For parts that we suspect are out of date but we're not sure how it should be updated, file issues like SpecialK out of date? #23. @pyrocto confirmed that he sees such issues.

@staff91 @qelentium we're not planning any regular meetings yet, but do look for an opportunity to talk with me on discord / zoom / hangouts / phone.

[rolandkofler]

Is rabbitmq still part of the new architecture?

[rolandkofler]

@dckc what is the purpose of translations? Technical audience generally must be able to read English documentation. With a few exceptions like programmers in China maybe. Is the target audience broader?

[dckc]

The purpose that interests me is that people who translated the architecture document know it well as a result.

[dckc]

rchain/mobile-process-calculi-for-blockchain#3 is still pending, since January.

[dckc]

The diagrams and such from the RChain VM talk by @leithaus and co in Boulder are really good. I hope to integrate them into an arch doc revision.

[dckc]

I made some review progress June 18; I used an rchain-archdoc discord server to take notes as I read along, and filed important stuff in the https://github.com/rchain/architecture-docs/ repo

[AyAyRon-P]

Hi @dckc is there any update for this issue or can we close this out and use it as a point of reference?

cc @pavlos1851

[dckc]

I still plan to work on it.

It's only tangentially related to Translation though...

[dckc]

@JoshOrndorff hopes to take a look at a chapter or so and sync with me next Thu.

I brainstormed a little with @TrenchFloat about some options too. I'll let him share.

[JoshOrndorff]

I've forked the repo to https://github.com/rchain-community/architecture-docs so we can collaborate and merge each others PRs without the lag time in the main rchain repo. Couple of big picture questions. @dckc @plantether

What should we do with stuff that is no longer in scope for the foreseeable like mobile process-friendly sharding? (I like 2)

1. Remove all traces of it
2. Mention that it still exists in old versions
3. Leave it but note that it is out of scope

What should we do with stuff that is no longer in scope for Mercury, but is still possible for patch releases to Mercury? (I like 3)

1. Remove all traces of it
2. Mention that it still exists in old versions
3. Leave it but note that it is out of scope for now

[edeykholt]

I suggest 1 and 1, and just document the planned Mercury architecture. That way, the architecture document revision will get done sooner and help the project adoption. An architecture roadmap document can be started, initially as a draft, as a separate document. There could be a paragraphs in the Mercury architecture document that bullets out the roadmap concepts (but not release schedules) at a high level, the epic-epic ideas, including process-friendly sharding, a RhoVM closer to the metal, skSNARKS, additional encryption curves, plugable consensus algos, quantum resistant stuff, etc. Thank you for taking this on!!!

[dckc]

The Mercury design isn't much to write home about. The architecture can be aspirational; we don't have to get there right away. The architecture document is a recruiting tool; at least it was in my case.

In what way is mobile process-friendly sharding out of scope?

Once we have composite shards, though, we can use a single currency among those. -- @pyrocto Aug 25, 2018

[dckc]

I've forked the repo to https://github.com/rchain-community/architecture-docs so we can collaborate and merge each others PRs without the lag time in the main rchain repo.

Oh. Commits there won't go to http://arch-doc.rchain.coop/ via readthedocs. Oh... strange... http://arch-doc.rchain.coop/ gives a blank nginx page. But https://rchain-architecture.readthedocs.io/en/latest/ is still there. I'll have to see if I can change the github source that rtd uses.

[JoshOrndorff]

I'm leaning closer to @edeykholt on this one. Would be nice to Document what people can expect to use once mainnet launches. I like the idea of keeping a second document with the aspirational stuff, but I think the existing version of the archdoc pretty much does that, no?

regarding the repo choice, I was thinking that not immediately publishing to RTD was a feature. Would be nice to have proof readers before we publish.

[plantether]

I agree with Ed about version 1 so we can get it out and with @dckc for version 2.

[JoshOrndorff]

Yeah, now that I keep thinking about it I like the idea of writing up the full aspiration to get everyone excited about the stuff that me excited. Explain the full vision of what building on the RhoVM could be.

I guess a better way to ask the question is: If we're going to keep all of the aspirational stuff, are there actually significant revisions to be made? I'm sure typos stylistic stuff, a few minor corrects exist. Is that what we're after? Or maybe going through and flagging things as "already implemented" "mercury scope" "venus scope" "hopefully someday"?

[dckc]

regarding the repo choice, I was thinking that not immediately publishing to RTD was a feature.

That's what branches and such are for, no? Why shouldn't a merged PR affect the published version?

[dckc]

If we're going to keep all of the aspirational stuff, are there actually significant revisions to be made? I'm sure typos stylistic stuff, a few minor corrects exist. Is that what we're after?

Indeed, one approach is to treat it like a museum piece. The note on the cover page (rchain/architecture-docs#32) might be all we need for that. I have also filed a few PRs for typos.

Or maybe going through and flagging things as "already implemented" "mercury scope" "venus scope" "hopefully someday"?

Yes, another approach is to annotate sections with pointers to details on how it actually got implemented.

As to which future release something is going into, that involves an ongoing maintenance burden when schedules change, so I'd rather avoid that.

My preferred approach to parts that aren't implemented yet but we know they aren't right is to abstract away the incorrect details, leaving less info, but what remains is correct.

[JoshOrndorff]

@dckc submitted a PR that links to developer.rchain.coop for info about what is currently implemented. rchain/architecture-docs#32

I like that idea a lot, and I suggest that we re-brand this doc slightly as the "RChain architecture Vision" or something similar. Then we can keep in all the cool stuff about powerset sharding and mobile processes and whatnot and make revision a smaller task.

Point well taken about using branches. But I'd say the difficulty getting the existing PR merged is evidence enough that we should develop elsewhere in the meantime.

[JoshOrndorff]

Looks like no PRs have been merged in rchain/architecture-docs sice March https://github.com/rchain/architecture-docs/pulls?utf8=%E2%9C%93&q=is%3Apr

[dckc]

So I was confused when I got the impression you have rights to merge those PRs?

…

On Fri, Oct 26, 2018, 6:46 AM Joshy Orndorff ***@***.***> wrote: Looks like no PRs have been merged in rchain/architecture-docs sice March https://github.com/rchain/architecture-docs/pulls?utf8=%E2%9C%93&q=is%3Apr — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#580 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAJNytDNM6izuEBJMz-wNa-et2nQUPQrks5uoxJTgaJpZM4TJRqD> .