docs: config #495

vasco-santos · 2019-12-04T16:41:50Z

One of the biggest issues that js-libp2p users usually have relies on being complicated to understand:

what is js-libp2p in the middle of so many repos?
what is a libp2p bundle?
how to configure js-libp2p?
how to configure X in js-libp2p?

Some decisions:

Get rid of the bundle naming

Some topics to discuss in the future:

Separate modules configuration from libp2p core configuration (will open an issue for this later)

Relevant issues:

Co-Authored-By: Alan Shaw <alan.shaw@protocol.ai>

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

doc/CONFIGURATION.md

jacobheun · 2019-12-04T18:02:03Z

doc/CONFIGURATION.md

+
+Considering libp2p's modular nature, it can be composed by a set of building blocks that enable users to create any type of p2p systems without needing to implement its network layer. Taking into account that each p2p system has its own needs and requirements, libp2p can be configured accordingly.
+
+`js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its building blocks.


I think this is superfluous.

Suggested change

`js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its building blocks.

Maybe I should move this under the next section? Its main intend is to introduce the modules

doc/CONFIGURATION.md

jacobheun · 2019-12-04T18:05:22Z

doc/CONFIGURATION.md

+
+## Modules
+
+For getting an instance of `js-libp2p` compliant with all types of networking requirements, it is possible to specify the following building blocks:


I think using subsystems instead of building blocks is a bit more descriptive.

jacobheun

Added some suggestions and a few comments. This is going to be a big improvement to the docs ❤️

yusefnapora

This is great @vasco-santos! I think @jacobheun covered things really well. I only have a little tweak to the peer routing description.

doc/CONFIGURATION.md

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

mcclure · 2019-12-07T22:00:37Z

My thoughts as a libp2p newbie:

This document is very clear! This would have helped me a lot if it had been linked when I first found js-libp2p, and honestly it helps me a lot even now. I have some comments:

I think it is okay to use the "bundle" terminology as long as you clearly explain "In the libp2p community, a 'bundle' is…" (…"a list of modules selected for a particular project?")
I would recommend listing, for each of your "transports", which platforms they work on, eg (desktop) or (browser) or (desktop/browser).
Are you a native German speaker? There were a small number of sentences that did not read to me like natural English. I recommend these fixes:

"This way, the user should install and import the modules that are relevant for their requirements" In this sentence I would remove "This way,", the sentence is entirely clear without it.

"Bear in mind that only a **transport** is required, being all the other subsystems optional." I would replace the word "being" with "with"

I noticed a spelling error "multiplxers" for "multiplexers"

Otherwise it was good!

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

Co-Authored-By: Yusef Napora <yusef@protocol.ai>

vasco-santos · 2019-12-09T09:56:07Z

Thanks for your feedback @mcclure

My thoughts as a libp2p newbie:

This document is very clear! This would have helped me a lot if it had been linked when I first found js-libp2p, and honestly it helps me a lot even now. I have some comments:

I think it is okay to use the "bundle" terminology as long as you clearly explain "In the libp2p community, a 'bundle' is…" (…"a list of modules selected for a particular project?")

The bundle naming caused confusion to several people and in the web space bundle is also used in other context. As a consequence, we thought it is a good timing to get rid of the bundle terminology.

I would recommend listing, for each of your "transports", which platforms they work on, eg (desktop) or (browser) or (desktop/browser).

I think that we can add that. I was thinking on writing that in the getting started document, but since it does not add too much noise here, I will add it

Are you a native German speaker? There were a small number of sentences that did not read to me like natural English. I recommend these fixes:

Not really, native portuguese speaker, but thanks for the recommendations. I will work on them

"This way, the user should install and import the modules that are relevant for their requirements" In this sentence I would remove "This way,", the sentence is entirely clear without it.
"Bear in mind that only a transport is required, being all the other subsystems optional." I would replace the word "being" with "with"
I noticed a spelling error "multiplxers" for "multiplexers"
Otherwise it was good!

Thanks for having a look on this and hopefully it will help you and other folks interested in getting started with libp2p

jacobheun

Added one minor suggestion, otherwise this looks good! I think we can do a final pass of all the docs before the final release.

doc/CONFIGURATION.md

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

* docs: new api * chore: new iteration * chore: apply suggestions from code review Co-Authored-By: Alan Shaw <alan.shaw@protocol.ai> * chore: apply suggestions from code review Co-Authored-By: Jacob Heun <jacobheun@gmail.com> * chore: address review * docs: add events * chore: apply suggestions from code review Co-Authored-By: Jacob Heun <jacobheun@gmail.com> * docs: configuration * chore: apply suggestions from code review Co-Authored-By: Jacob Heun <jacobheun@gmail.com> * chore: update peer routing description Co-Authored-By: Yusef Napora <yusef@protocol.ai> * chore: decouple examples * chore: address pr comment * fix: connection encryption is required * chore: apply review suggestion Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

vasco-santos and others added 5 commits November 28, 2019 16:12

docs: new api

e244170

chore: new iteration

e9158bd

chore: apply suggestions from code review

4d9eabd

Co-Authored-By: Alan Shaw <alan.shaw@protocol.ai>

chore: apply suggestions from code review

cfa0136

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

chore: address review

5de2e22

vasco-santos requested review from alanshaw, jacobheun and yusefnapora December 4, 2019 16:43

vasco-santos mentioned this pull request Dec 4, 2019

docs: new api #472

Merged

docs: add events

5699779

vasco-santos force-pushed the docs/new-api branch from f6d8000 to 5699779 Compare December 4, 2019 17:10

vasco-santos force-pushed the docs/config branch from 76b808d to 1f8843d Compare December 4, 2019 17:13

jacobheun suggested changes Dec 4, 2019

View reviewed changes

yusefnapora approved these changes Dec 4, 2019

View reviewed changes

doc/CONFIGURATION.md Outdated Show resolved Hide resolved

chore: apply suggestions from code review

40e3e6b

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

vasco-santos and others added 4 commits December 9, 2019 10:49

docs: configuration

4a563d3

chore: apply suggestions from code review

4cb6d1d

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

chore: update peer routing description

fd1d796

Co-Authored-By: Yusef Napora <yusef@protocol.ai>

chore: decouple examples

19b52f1

chore: address pr comment

fc98809

vasco-santos force-pushed the docs/config branch from 669a812 to fc98809 Compare December 9, 2019 10:19

fix: connection encryption is required

0d631dd

jacobheun approved these changes Dec 10, 2019

View reviewed changes

doc/CONFIGURATION.md Outdated Show resolved Hide resolved

chore: apply review suggestion

4df8471

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

vasco-santos changed the base branch from docs/new-api to refactor/async-await December 10, 2019 14:35

Merge branch 'refactor/async-await' into docs/config

44010f8

jacobheun merged commit c162e59 into refactor/async-await Dec 10, 2019

jacobheun deleted the docs/config branch December 10, 2019 20:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: config #495

docs: config #495

vasco-santos commented Dec 4, 2019 •

edited

Loading

jacobheun Dec 4, 2019

vasco-santos Dec 4, 2019

jacobheun Dec 4, 2019

jacobheun left a comment

yusefnapora left a comment

mcclure commented Dec 7, 2019

vasco-santos commented Dec 9, 2019

jacobheun left a comment


		Considering libp2p's modular nature, it can be composed by a set of building blocks that enable users to create any type of p2p systems without needing to implement its network layer. Taking into account that each p2p system has its own needs and requirements, libp2p can be configured accordingly.

		`js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its building blocks.


		## Modules

		For getting an instance of `js-libp2p` compliant with all types of networking requirements, it is possible to specify the following building blocks:

docs: config #495

docs: config #495

Conversation

vasco-santos commented Dec 4, 2019 • edited Loading

jacobheun Dec 4, 2019

Choose a reason for hiding this comment

vasco-santos Dec 4, 2019

Choose a reason for hiding this comment

jacobheun Dec 4, 2019

Choose a reason for hiding this comment

jacobheun left a comment

Choose a reason for hiding this comment

yusefnapora left a comment

Choose a reason for hiding this comment

mcclure commented Dec 7, 2019

vasco-santos commented Dec 9, 2019

jacobheun left a comment

Choose a reason for hiding this comment

vasco-santos commented Dec 4, 2019 •

edited

Loading