Skip to content
New issue

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

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

change(docs): Update 'Design Overview' page of Zebra book #5892

Merged
merged 5 commits into from
Jan 10, 2023

Conversation

arya2
Copy link
Contributor

@arya2 arya2 commented Dec 23, 2022

Motivation

We want to update the design overview page with some notable blog posts and a graph of service dependencies to help new developers understand zebrad faster.

Closes #2740.

Solution

  • Add links to notable blog posts
  • Add a simplified graph of service dependencies

Related changes:

  • Correction of issue/PR references in Pipelineable Block Lookup RFC
  • Remove some out-of-date text

Review

Anyone can review.

Reviewer Checklist

  • Will the PR name make sense to users?
    • Does it need extra CHANGELOG info? (new features, breaking changes, large changes)
  • Are the PR labels correct?
  • Does the code do what the ticket and PR says?
    • Does it change concurrent code, unsafe code, or consensus rules?
  • How do you know it works? Does it have tests?

- a simplified graph of service dependencies in design overview
- links to notable blog posts
- removals of some out-of-date text

also corrects issue/pr refs in an rfc
@arya2 arya2 requested a review from a team as a code owner December 23, 2022 01:09
@arya2 arya2 requested review from teor2345 and removed request for a team December 23, 2022 01:09
@arya2 arya2 added A-docs Area: Documentation P-Low ❄️ labels Dec 23, 2022
@arya2 arya2 self-assigned this Dec 23, 2022
@github-actions github-actions bot added the C-enhancement Category: This is an improvement label Dec 23, 2022
@arya2 arya2 requested review from conradoplg, oxarbitrage and a team and removed request for teor2345 December 23, 2022 01:10
@arya2
Copy link
Contributor Author

arya2 commented Dec 23, 2022

Here's the input for the graph:

digraph services {
    state -> transaction_verifier
    state -> mempool
    state -> chain_verifier
    transaction_verifier -> mempool
    transaction_verifier -> chain_verifier
    mempool -> inbound
    chain_verifier -> inbound
    chain_verifier -> syncer
    inbound -> peer_set
    peer_set -> syncer
    peer_set -> mempool
}

Rendered here

I tried making it comprehensive at first but it seemed to grow unnecessarily complicated, so I left in what I thought would be most useful.

I'm open to suggestions on what should be included.

This is what looks like rendered in the dark themes*:

image

*in most browsers, see https://caniuse.com/css-filters

@arya2 arya2 changed the title change(docs): Updates Design Overview page of Zebra book. change(docs): Update 'Design Overview' page of Zebra book. Dec 23, 2022
@arya2 arya2 added the no-review-reminders Turn off review reminders label Dec 23, 2022
Copy link
Contributor

@teor2345 teor2345 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, looks great!

There are no blockers here, except for an arrow on a diagram that I think is the wrong way around?

book/src/dev/overview.md Show resolved Hide resolved
book/book.toml Show resolved Hide resolved
@teor2345 teor2345 changed the title change(docs): Update 'Design Overview' page of Zebra book. change(docs): Update 'Design Overview' page of Zebra book Jan 4, 2023
@teor2345 teor2345 added the C-trivial Category: A trivial change that is not worth mentioning in the CHANGELOG label Jan 4, 2023
@teor2345
Copy link
Contributor

teor2345 commented Jan 5, 2023

Can you add the source of the diagram and the online tool you used to generate it in a markdown comment?
(I think they work the same as HTML comments.)

That way, anyone can edit the diagram if they want.

mergify bot added a commit that referenced this pull request Jan 10, 2023
@mergify mergify bot merged commit 99cbffb into main Jan 10, 2023
@mergify mergify bot deleted the book-dev-overview branch January 10, 2023 10:10
@oxarbitrage oxarbitrage mentioned this pull request Jan 29, 2023
36 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation C-enhancement Category: This is an improvement C-trivial Category: A trivial change that is not worth mentioning in the CHANGELOG no-review-reminders Turn off review reminders
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Documentation: link to Zebra architecture blog posts in zebrad overview for devs in the book
2 participants