search

rchain / bounties

RChain Bounty Program
MIT License
90 stars 59 forks source link

RChain Architecture document revision #580

Open dckc opened 6 years ago

dckc commented 6 years ago

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

Candidates:

cc @Jake-Gillberg

ghost commented 6 years ago

@dckc ok

qelentium commented 6 years ago

@dckc im in! :)

dckc commented 6 years ago

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

dckc commented 6 years ago

@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 commented 6 years ago

Is rabbitmq still part of the new architecture?

rolandkofler commented 6 years ago

@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 commented 6 years ago

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

dckc commented 6 years ago

https://github.com/rchain/mobile-process-calculi-for-blockchain/pull/3 is still pending, since January.

dckc commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

I still plan to work on it.

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

dckc commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

JoshOrndorff commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 (https://github.com/rchain/architecture-docs/pull/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 commented 6 years ago

@dckc submitted a PR that links to developer.rchain.coop for info about what is currently implemented. https://github.com/rchain/architecture-docs/pull/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 commented 6 years ago

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 commented 6 years ago

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 notifications@github.com 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 https://github.com/rchain/bounties/issues/580#issuecomment-433413253, or mute the thread https://github.com/notifications/unsubscribe-auth/AAJNytDNM6izuEBJMz-wNa-et2nQUPQrks5uoxJTgaJpZM4TJRqD .