docs: adding site docs for 09-localhost client #3147

damiannolan · 2023-02-15T09:28:04Z

Description

closes: #3055

Commit Message / Changelog Entry

docs: adding site docs for 09-localhost client

see the guidelines for commit messages. (view raw markdown for examples)

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

Targeted PR against correct branch (see CONTRIBUTING.md).
Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
Code follows the module structure standards and Go style guide.
Wrote unit and integration tests.
Updated relevant documentation (docs/) or specification (x/<module>/spec/).
Added relevant godoc comments.
Provide a commit message to be used for the changelog entry in the PR description for review.
Re-reviewed Files changed in the Github PR explorer.
Review Codecov Report in the comment section below once CI passes.

damiannolan · 2023-02-22T15:58:10Z

Feel free to make any suggestions and/or push to this branch 🙌

docs/ibc/light-clients/localhost/connection.md

tmsdkeys

Thanks for starting this @damiannolan ! I have some suggestions in terms of the narrative:

I can imagine the use cases of the localhost client/connection is not trivially clear, so it would make sense to me to add some more explanation. Question is whether we elaborate here or write a complementary product focused blog post and link to it here...
Given the localhost client has some differences at the transport layer (while attempting to preserve application level interface afaiu), I think it'd be good to list all of these differences in the overview. I was thinking of a table format even, comparing localhost and a 'regular' client (not localhost or solomachine). The differences are discussed throughout the docs but I think it would be nice to have an overview table

I can take a stab at this

damiannolan · 2023-02-23T14:26:45Z

I can imagine the use cases of the localhost client/connection is not trivially clear, so it would make sense to me to add some more explanation. Question is whether we elaborate here or write a complementary product focused blog post and link to it here...

There's some notes about use cases in the requirements doc in #3120 but yeah, either adding something here or in a blogpost would be good too for visibility.

docs/ibc/light-clients/localhost/state-verification.md

tmsdkeys · 2023-02-27T15:23:20Z

I've made the following changes:

added a context paragraph
split integration.md from the overview
added a comparison table localhost vs 'regular' client to the overview

Please check if I got all of it in the table...

docs/ibc/light-clients/localhost/overview.md

colin-axner

Thank you for starting this work!! I left various comments, but overall looks good to me!

docs/ibc/light-clients/localhost/client-state.md

docs/ibc/light-clients/localhost/connection.md

docs/ibc/light-clients/localhost/integration.md

docs/ibc/light-clients/localhost/overview.md

colin-axner · 2023-02-27T16:35:37Z

docs/ibc/light-clients/localhost/overview.md

+| Number of connection(s) | many connections, 1 (or more) per client | single sentinel `ConnectionEnd` representing a connection |
+| Connection creation | connection handshake, provided underlying client | the `ConnectionEnd` is created and set in store via the `InitGenesis` handler of the 03-connection submodule in core IBC |
+| Counterparty | underlying client, representing another chain | `09-localhost` |
+| Channel creation | channel handshake, provided underlying connection | channel handshake, **out of the box** |


What does this mean? It seems a bit "hype" to me. "out of the box" isn't very impressive in this situation since it's just talking about a connection existing. It takes less than 30 seconds to initiate a connection using "regular clients". I think I'd prefer to minimize the amount of information that has to be read and assume the reader is able to deduce that channels can be immediately created using the sentinel localhost connection

I've removed the "Channel Creation" row as channels are more or less treated the same

Didn't intend to be claiming it was an 'impressive' feat by any means :) My thinking here was "what does all of this mean if I'm a dev who wants to start testing with localhost when used to a setup having 2 chains"? And then the only thing changing really from that POV is that I can immediately create my channel vs first having to create client and connection... so more pragmatic than hype

Sure the reader could deduct it, but that holds for everything in the table. I personally just like when I can quickly gather all info from an overview table when I need a quick reminder

That makes sense. Apologies if my comment seemed strong, that wasn't the intention. I'm just looking to make sure the language remains neutral.

I have no preference if we keep this section but maybe we could use the wording "channel handshake on top of existing connection end connection-localhost" or something like that

no worries, I learned now you don't like hype trains lol 🚂

docs/ibc/light-clients/localhost/overview.md

…3213) * Revert "Adding documentation for disabling localhost client (#3188)" This reverts commit 5fa3f33. * chore: add back relevant docs

crodriguezvega

Thank a lot for this, @damiannolan

docs/ibc/light-clients/localhost/overview.md

docs/ibc/light-clients/localhost/integration.md

docs/ibc/light-clients/localhost/connection.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io> Co-authored-by: colin axnér <25233464+colin-axner@users.noreply.github.com>

chatton

LGTM! Thanks for all the work with these docs ❤️

docs/ibc/light-clients/localhost/overview.md

tmsdkeys

LGTM, thanks for finishing this up!

Co-authored-by: tmsdkeys <98807841+tmsdkeys@users.noreply.github.com>

colin-axner

Great work! Many thanks to everyone who spent time on this! :)

damiannolan added 6 commits February 9, 2023 00:35

initial draft

601dafa

update wording

e3dde7e

Merge branch '09-localhost' into damian/localhost-docs

9785fba

update docs and add code snippets

8fb5455

doc updates

9350b51

adding localhost sentinel connection end info

a1bf7c6

crodriguezvega added the backport-to-v7.1.x label Feb 21, 2023

chatton and others added 4 commits February 22, 2023 12:05

Adding documentation for disabling localhost client (#3188)

5fa3f33

updating docs with state verification notes

a90899d

formatting

3503576

adding AppModuleBasic wiring

750a87d

damiannolan marked this pull request as ready for review February 22, 2023 15:55

damiannolan requested review from colin-axner, AdityaSripal, crodriguezvega, charleenfei, chatton and tmsdkeys as code owners February 22, 2023 15:55

tmsdkeys reviewed Feb 23, 2023

View reviewed changes

docs/ibc/light-clients/localhost/connection.md Show resolved Hide resolved

tmsdkeys reviewed Feb 23, 2023

View reviewed changes

update config to seperate integration.md from overview.md

da98d24

crodriguezvega removed the backport-to-v7.1.x label Feb 24, 2023

Thomas Dekeyser added 3 commits February 24, 2023 16:22

add use case context to overview

2eaf70c

add table to overview.md

8bb9c2c

estethic fixes

d1eab80

tmsdkeys reviewed Feb 27, 2023

View reviewed changes

docs/ibc/light-clients/localhost/state-verification.md Show resolved Hide resolved

tmsdkeys reviewed Feb 27, 2023

View reviewed changes

docs/ibc/light-clients/localhost/overview.md Outdated Show resolved Hide resolved

colin-axner reviewed Feb 27, 2023

View reviewed changes

colin-axner and others added 2 commits February 27, 2023 17:57

Revert "Adding documentation for disabling localhost client (#3188)" (#…

31b031e

…3213) * Revert "Adding documentation for disabling localhost client (#3188)" This reverts commit 5fa3f33. * chore: add back relevant docs

code blocks alignment

e5a3ae8

crodriguezvega reviewed Feb 28, 2023

View reviewed changes

chatton reviewed Mar 1, 2023

View reviewed changes

docs/ibc/light-clients/localhost/connection.md Outdated Show resolved Hide resolved

damiannolan and others added 10 commits March 1, 2023 11:32

updating connection code snippet

0647be3

Apply suggestions from code review

f40b950

Co-authored-by: Carlos Rodriguez <carlos@interchain.io> Co-authored-by: colin axnér <25233464+colin-axner@users.noreply.github.com>

remove client support table entry

700ef35

Merge branch '09-localhost' into damian/localhost-docs

629bd52

updating integration docs, adding sentintel proof info

b46fe86

updating code snippets

7657456

complete todos

c440277

table updates

6a3613f

adding note about disallowed connection handshakes

8fef7bd

use release tag in code link

7b74a46

chatton approved these changes Mar 1, 2023

View reviewed changes

reorder table rows

569aa48

tmsdkeys reviewed Mar 1, 2023

View reviewed changes

docs/ibc/light-clients/localhost/overview.md Show resolved Hide resolved

tmsdkeys approved these changes Mar 1, 2023

View reviewed changes

Update docs/ibc/light-clients/localhost/overview.md

581e06b

Co-authored-by: tmsdkeys <98807841+tmsdkeys@users.noreply.github.com>

colin-axner approved these changes Mar 1, 2023

View reviewed changes

damiannolan merged commit 7303ce3 into 09-localhost Mar 1, 2023

damiannolan deleted the damian/localhost-docs branch March 1, 2023 15:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: adding site docs for 09-localhost client #3147

docs: adding site docs for 09-localhost client #3147

damiannolan commented Feb 15, 2023 •

edited

Loading

damiannolan commented Feb 22, 2023

tmsdkeys left a comment

damiannolan commented Feb 23, 2023

tmsdkeys commented Feb 27, 2023

colin-axner left a comment

colin-axner Feb 27, 2023

damiannolan Mar 1, 2023

tmsdkeys Mar 1, 2023

colin-axner Mar 1, 2023

tmsdkeys Mar 1, 2023

crodriguezvega left a comment

chatton left a comment

tmsdkeys left a comment

colin-axner left a comment

docs: adding site docs for 09-localhost client #3147

docs: adding site docs for 09-localhost client #3147

Conversation

damiannolan commented Feb 15, 2023 • edited Loading

Description

Commit Message / Changelog Entry

damiannolan commented Feb 22, 2023

tmsdkeys left a comment

Choose a reason for hiding this comment

damiannolan commented Feb 23, 2023

tmsdkeys commented Feb 27, 2023

colin-axner left a comment

Choose a reason for hiding this comment

colin-axner Feb 27, 2023

Choose a reason for hiding this comment

damiannolan Mar 1, 2023

Choose a reason for hiding this comment

tmsdkeys Mar 1, 2023

Choose a reason for hiding this comment

colin-axner Mar 1, 2023

Choose a reason for hiding this comment

tmsdkeys Mar 1, 2023

Choose a reason for hiding this comment

crodriguezvega left a comment

Choose a reason for hiding this comment

chatton left a comment

Choose a reason for hiding this comment

tmsdkeys left a comment

Choose a reason for hiding this comment

colin-axner left a comment

Choose a reason for hiding this comment

damiannolan commented Feb 15, 2023 •

edited

Loading