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

Adds new page with 4 best practices #1079

Merged
merged 12 commits into from
Mar 23, 2022
Merged

Conversation

Annamarie2019
Copy link
Contributor

@Annamarie2019 Annamarie2019 commented Mar 14, 2022

Creates a new page with these 4 best practices (Issue #491):

  • use cidv1 for future-proof addressing, and use in case-insensitive contexts
  • enable pubsub if you need fast IPNS
  • enable GC if your data churn is expected to be high
  • use subdomain gateways or DNSLink when publishing apps

@johnnymatthews : How do I get the new page into the directory? I'm thinking it should go into How-tos > Customize your install, right before Troubleshooting.

@johnnymatthews
Copy link
Contributor

I've added the sidebar stuff so this new page now shows up!

image

Do you think the title of this page is a bit too long though? Is there anyway we can shorten it a bit?

@Annamarie2019 Annamarie2019 marked this pull request as ready for review March 15, 2022 21:38
@Annamarie2019 Annamarie2019 marked this pull request as draft March 15, 2022 21:53
Copy link
Member

@lidel lidel left a comment

Choose a reason for hiding this comment

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

Thank you @Annamarie2019!

Added some clarifications around IPNS over pubsub

docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
@Annamarie2019 Annamarie2019 marked this pull request as ready for review March 17, 2022 13:20
@Annamarie2019
Copy link
Contributor Author

@lidel and @johnnymatthews It looks like it's in there the way I intended now. (@lidel I removed the link that seemed to refer to the previous version of the code we had.)

Copy link
Member

@lidel lidel left a comment

Choose a reason for hiding this comment

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

Looks good, but I think the pubsub section is still confusing, see my comment below.

ps. I fixed some links

docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved

## Enable pubsub if you need fast IPNS

Pubsub is one of the available options for configuring your IPFS node. It allows you to publish and subscribe to messages on a given topic. It can be a quick alternative to accessing data instead of setting up [IPNS](../concepts/ipns/#interplanetary-name-system-ipns). Pubsub is an experimental feature and it should not be used in a production environment. It is disabled by default.
Copy link
Member

@lidel lidel Mar 17, 2022

Choose a reason for hiding this comment

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

This mixes two distinct concepts: "Pubsub" is a thing on its own, but here we talk about "IPNS over Pubsub" which will enable "Pubsub" and use it for faster IPNS record lookups.

In reality, people use this in production, so we should soften the warning and just ask people to be mindful when they opt-in.

Perhaps we could clarify this around these lines:

Suggested change
Pubsub is one of the available options for configuring your IPFS node. It allows you to publish and subscribe to messages on a given topic. It can be a quick alternative to accessing data instead of setting up [IPNS](../concepts/ipns/#interplanetary-name-system-ipns). Pubsub is an experimental feature and it should not be used in a production environment. It is disabled by default.
"[IPNS](../concepts/ipns/#interplanetary-name-system-ipns) over [Pubsub](../concepts/glossary/#pubsub)" is a way to accelerate publishing and resolution of IPNS records by asking both pubsub topic and DHT. It is an experimental feature and it should be used with care. It is disabled by default.

@Annamarie2019
Copy link
Contributor Author

@johnnymatthews @lidel Since the last time you reviewed this, I changed one piece:

"## Enable pubsub for fast IPNS

As a standalone feature, pubsub is a way to publish and subscribe to messages. However, within ipns, you can use it to accelerate publishing and resolution of IPNS records. Within IPNS, pubsub calls both the topic and the DHT (Distributed Hash Table) key of the IPNS. Pubsub is an experimental feature, so use it with care. It's disabled by default."

I see Marcin's suggestion is still here above if you need a comparison. I need you to have my back when I change what I think is better English, but maybe I got rid of some accepted engineer-speak. Thanks.

Copy link
Member

@lidel lidel left a comment

Choose a reason for hiding this comment

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

LGTM!

(I removed one sentence that was bit technically incorrect/confusing + we already had it phrased in a better way in sentence after the shell example)

docs/how-to/best-practices-for-ipfs-builders.md Outdated Show resolved Hide resolved
@filecorgi
Copy link
Contributor

  • Image optimization came back clean!
  • Vuepress build was successful!

@johnnymatthews johnnymatthews merged commit 1aff741 into main Mar 23, 2022
@johnnymatthews johnnymatthews deleted the builders-best-practices branch March 23, 2022 15:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create a “best practices for busy builders” page.
4 participants