From ad3350466933c72ae9d54acafd3f39c4fdb67004 Mon Sep 17 00:00:00 2001 From: "jackson1.annemarie@gmail.com" Date: Mon, 14 Mar 2022 15:20:12 -0700 Subject: [PATCH 1/8] Adds new page with 4 best practices --- docs/how-to/best-practices-for-ipfs-builders | 65 ++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/how-to/best-practices-for-ipfs-builders diff --git a/docs/how-to/best-practices-for-ipfs-builders b/docs/how-to/best-practices-for-ipfs-builders new file mode 100644 index 000000000..ef4ac81dd --- /dev/null +++ b/docs/how-to/best-practices-for-ipfs-builders @@ -0,0 +1,65 @@ +--- +title: Best practices for IPFS builders +description: Some IPFS features are disabled or not defaults, but we encourage their use under the right circumstances. We list them here for easy access by busy builders. +date: 2022-03-11 +--- + +# Best practices for IPFS builders + +Some IPFS features are not enabled or set as defaults, but we encourage you to use them under the right circumstances. We list them here for easy access. + +## When is CIDv1 the best choice + +There are two versions of CIDs (Content Identifiers), CIDv0 and CIDv1. + +CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. Many of the existing IPFS tools still generate CIDs in v0. [examples?] + +Some features use CIDv1 by default: +- `files` ([Mutable File System](file-systems.md#mutable-file-system-mfs)) +- `object` operations + +Use CIDv1 when you want: +- future-proof addressing +- case-insensitive addressing + +To opt in, use a version flag in the CLI: `ipfs add --cid-version 1`. + +To differentiate between hashes already created, notice that CIDv0 starts with `Qm`. + +For more information on content addressing and CID versions, see [Content Addressing and CIDs](https://docs.ipfs.io/concepts/content-addressing/#content-addressing-and-cids). + +## 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. + +`pubsub` is an experimental feature. It's not intended in its current state to be used in a production environment, so it's disabled by default. + +To use this feature, enable it when you run the daemon in the CLI with `ipfs --enable-pubsub-experiment`. + +See [ipfs pubsub](../reference/cli/#ipfs-pubsub) for information on the available subcommands. + +## Enable Garbage Collection if your data churn is expected to be high + +Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called garbage collection. + +If you expect your data churn to be high, you may want to enable garbage collection to reclaim memory occupied by objects that are no longer in use. + +However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. See: +- [Persistence, permanence, and pinning](../concepts/persistence/#persistence-permanence-and-pinning) +- [Pinning in context](https://docs.ipfs.io/concepts/persistence/#pinning-in-context) +- [Pin files using IPFS](./how-to/pin-files/#three-kinds-of-pins). + +Then you can safely enable garbage collection for all other data. See: +- [Garbage collection](../concepts/persistence/#garbage-collection) +- [api/v0/repo/gc](../reference/http/api/#api-v0-repo-gc) + +## Use subdomain gateways or DNSLink when publishing apps for secure context and origin isolation + +To prevent one website from improperly accessing HTTP session data associated with a different website, use a: +- subdomain gateway, or +- DNSLink + +See: +- [Violation of same-origin policy](../concepts/ipfs-gateway/#limitations-and-potential-workarounds) +-[Subdomain gateway](./how-to/address-ipfs-on-web/#subdomain-gateway) +-[DNSLink gateway](./how-to/address-ipfs-on-web/#http-gateways) From daa51ca58b4a93354cf14f6ed5e1753202048c38 Mon Sep 17 00:00:00 2001 From: johnnymatthews Date: Mon, 14 Mar 2022 19:03:11 -0400 Subject: [PATCH 2/8] Adds new page to sidebar. Minor copy edits. --- docs/.vuepress/config.js | 1 + ...rs => best-practices-for-ipfs-builders.md} | 46 +++++++++++-------- package-lock.json | 1 + 3 files changed, 30 insertions(+), 18 deletions(-) rename docs/how-to/{best-practices-for-ipfs-builders => best-practices-for-ipfs-builders.md} (57%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index dea8ac22a..0290c54c1 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -178,6 +178,7 @@ module.exports = { 'https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/custom-ipfs-repo', 'Customize an IPFS repo' ], + '/how-to/best-practices-for-ipfs-builders', '/how-to/troubleshooting' ] }, diff --git a/docs/how-to/best-practices-for-ipfs-builders b/docs/how-to/best-practices-for-ipfs-builders.md similarity index 57% rename from docs/how-to/best-practices-for-ipfs-builders rename to docs/how-to/best-practices-for-ipfs-builders.md index ef4ac81dd..28600489c 100644 --- a/docs/how-to/best-practices-for-ipfs-builders +++ b/docs/how-to/best-practices-for-ipfs-builders.md @@ -1,52 +1,60 @@ --- -title: Best practices for IPFS builders -description: Some IPFS features are disabled or not defaults, but we encourage their use under the right circumstances. We list them here for easy access by busy builders. -date: 2022-03-11 +title: "Best practices for IPFS builders" +description: "Some IPFS features are disabled or not defaults, but we encourage their use under the right circumstances. We list them here for easy access by busy builders." --- # Best practices for IPFS builders -Some IPFS features are not enabled or set as defaults, but we encourage you to use them under the right circumstances. We list them here for easy access. +Some IPFS features are not enabled or set as defaults, but we encourage you to use them under the right circumstances. ## When is CIDv1 the best choice -There are two versions of CIDs (Content Identifiers), CIDv0 and CIDv1. +There are two versions of context identifiers (CIDs): CIDv0 and CIDv1. -CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. Many of the existing IPFS tools still generate CIDs in v0. [examples?] +CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. Many of the existing IPFS tools still generate CIDs in v0. You can quickly tell the difference between v0 and v1 CIDs since v0 CIDs always start with `Qm`. + + Some features use CIDv1 by default: + - `files` ([Mutable File System](file-systems.md#mutable-file-system-mfs)) - `object` operations -Use CIDv1 when you want: +We recommend you use CIDv1 when you want: + - future-proof addressing - case-insensitive addressing -To opt in, use a version flag in the CLI: `ipfs add --cid-version 1`. +To opt in, use the `--cid-version` flag in the CLI: -To differentiate between hashes already created, notice that CIDv0 starts with `Qm`. +```shell +ipfs add --cid-version 1 +``` For more information on content addressing and CID versions, see [Content Addressing and CIDs](https://docs.ipfs.io/concepts/content-addressing/#content-addressing-and-cids). ## 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. +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. Pubsub is an experimental feature and it should not be used in a production environment. It is disabled by default. -`pubsub` is an experimental feature. It's not intended in its current state to be used in a production environment, so it's disabled by default. +To use this feature, use the `--enable-pubsub-experiment` option when starting the IPFS daemon: -To use this feature, enable it when you run the daemon in the CLI with `ipfs --enable-pubsub-experiment`. +```shell +ipfs --enable-pubsub-experiment +``` -See [ipfs pubsub](../reference/cli/#ipfs-pubsub) for information on the available subcommands. +See [IPFS pubsub](../reference/cli/#ipfs-pubsub) for more information on the available subcommands. -## Enable Garbage Collection if your data churn is expected to be high +## Enable garbage collection if your data churn is expected to be high -Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called garbage collection. +Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called _garbage collection_. If you expect your data churn to be high, you may want to enable garbage collection to reclaim memory occupied by objects that are no longer in use. -However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. See: +However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. The following pages are useful for learning how pinning works: + - [Persistence, permanence, and pinning](../concepts/persistence/#persistence-permanence-and-pinning) -- [Pinning in context](https://docs.ipfs.io/concepts/persistence/#pinning-in-context) +- [Pinning in context](../concepts/persistence/#pinning-in-context) - [Pin files using IPFS](./how-to/pin-files/#three-kinds-of-pins). Then you can safely enable garbage collection for all other data. See: @@ -56,10 +64,12 @@ Then you can safely enable garbage collection for all other data. See: ## Use subdomain gateways or DNSLink when publishing apps for secure context and origin isolation To prevent one website from improperly accessing HTTP session data associated with a different website, use a: + - subdomain gateway, or - DNSLink -See: +For more information on security and gateways, take a look at these pages: + - [Violation of same-origin policy](../concepts/ipfs-gateway/#limitations-and-potential-workarounds) -[Subdomain gateway](./how-to/address-ipfs-on-web/#subdomain-gateway) -[DNSLink gateway](./how-to/address-ipfs-on-web/#http-gateways) diff --git a/package-lock.json b/package-lock.json index 94e2ae8d0..557fe2d9f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5,6 +5,7 @@ "requires": true, "packages": { "": { + "name": "ipfs-docs", "version": "2.0.0", "license": "MIT", "devDependencies": { From 380d8274b6c493d672c320d7193536f0b3c68857 Mon Sep 17 00:00:00 2001 From: "jackson1.annemarie@gmail.com" Date: Tue, 15 Mar 2022 14:24:03 -0700 Subject: [PATCH 3/8] V1 examples, what's future-proof, why pubsub fast --- docs/how-to/best-practices-for-ipfs-builders | 47 +++++++++++++------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/how-to/best-practices-for-ipfs-builders b/docs/how-to/best-practices-for-ipfs-builders index ef4ac81dd..2170b00df 100644 --- a/docs/how-to/best-practices-for-ipfs-builders +++ b/docs/how-to/best-practices-for-ipfs-builders @@ -6,60 +6,75 @@ date: 2022-03-11 # Best practices for IPFS builders -Some IPFS features are not enabled or set as defaults, but we encourage you to use them under the right circumstances. We list them here for easy access. +Some IPFS features are not enabled or set as defaults, but we encourage you to use them under the right circumstances. -## When is CIDv1 the best choice +## Use CIDv1 for future-proof addressing and case-insenstive contexts There are two versions of CIDs (Content Identifiers), CIDv0 and CIDv1. -CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. Many of the existing IPFS tools still generate CIDs in v0. [examples?] +CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. You can quickly tell the difference between v0 and v1 CIDs since v0 CIDs always start with `Qm`. Many of the existing IPFS tools still generate CIDs in v0, for example: + +- [IPFS Desktop](http://docs.ipfs.io.ipns.localhost:8080/install/ipfs-desktop/#ipfs-desktop) +- [/api/v0/add](https://docs.ipfs.io/reference/http/api/#api-v0-add), where the `cid-version` defaults to 0 unless an option that depends on CIDv1 is passed. Some features use CIDv1 by default: -- `files` ([Mutable File System](file-systems.md#mutable-file-system-mfs)) -- `object` operations + +- `files` ([Mutable File System](../concepts/file-systems/#mutable-file-system-mfs)) +- `object` operations ([ipfs object](https://docs.ipfs.io/reference/cli/#ipfs-object)) Use CIDv1 when you want: -- future-proof addressing -- case-insensitive addressing -To opt in, use a version flag in the CLI: `ipfs add --cid-version 1`. +- future-proof addressing: CIDv1 provides leading identifiers, such as [multicodec](https://github.com/multiformats/multicodec), which indicate the format of the target content so that the CID can support future CID formats. +- case-insensitive addressing for more flexibility + +To opt in, use the `--cid-version` flag in the CLI: + +```shell +ipfs add --cid-version 1 +``` -To differentiate between hashes already created, notice that CIDv0 starts with `Qm`. +To convert a CID from v0 to v1, see [CID conversion](https://docs.ipfs.io/concepts/content-addressing/#cid-conversion). For more information on content addressing and CID versions, see [Content Addressing and CIDs](https://docs.ipfs.io/concepts/content-addressing/#content-addressing-and-cids). ## 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. +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. -`pubsub` is an experimental feature. It's not intended in its current state to be used in a production environment, so it's disabled by default. +To use this feature, use the `--enable-pubsub-experiment` option when starting the IPFS daemon: -To use this feature, enable it when you run the daemon in the CLI with `ipfs --enable-pubsub-experiment`. +```shell +ipfs --enable-pubsub-experiment +``` See [ipfs pubsub](../reference/cli/#ipfs-pubsub) for information on the available subcommands. ## Enable Garbage Collection if your data churn is expected to be high -Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called garbage collection. +Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called _garbage collection_. If you expect your data churn to be high, you may want to enable garbage collection to reclaim memory occupied by objects that are no longer in use. -However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. See: +However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. The following pages are useful for learning how pinning works: + - [Persistence, permanence, and pinning](../concepts/persistence/#persistence-permanence-and-pinning) - [Pinning in context](https://docs.ipfs.io/concepts/persistence/#pinning-in-context) - [Pin files using IPFS](./how-to/pin-files/#three-kinds-of-pins). Then you can safely enable garbage collection for all other data. See: + - [Garbage collection](../concepts/persistence/#garbage-collection) - [api/v0/repo/gc](../reference/http/api/#api-v0-repo-gc) ## Use subdomain gateways or DNSLink when publishing apps for secure context and origin isolation To prevent one website from improperly accessing HTTP session data associated with a different website, use a: + - subdomain gateway, or - DNSLink See: + - [Violation of same-origin policy](../concepts/ipfs-gateway/#limitations-and-potential-workarounds) --[Subdomain gateway](./how-to/address-ipfs-on-web/#subdomain-gateway) --[DNSLink gateway](./how-to/address-ipfs-on-web/#http-gateways) +- [Subdomain gateway](./how-to/address-ipfs-on-web/#subdomain-gateway) +- [DNSLink gateway](./how-to/address-ipfs-on-web/#http-gateways) From 40b97a330da6c112c7d8d6d43baa580a0eb9c8a3 Mon Sep 17 00:00:00 2001 From: "jackson1.annemarie@gmail.com" Date: Thu, 17 Mar 2022 06:32:15 -0700 Subject: [PATCH 4/8] Adds "From this point on" & line spacing --- .../best-practices-for-ipfs-builders.md | 54 +++++-------------- 1 file changed, 14 insertions(+), 40 deletions(-) diff --git a/docs/how-to/best-practices-for-ipfs-builders.md b/docs/how-to/best-practices-for-ipfs-builders.md index fa9a566d3..015a23558 100644 --- a/docs/how-to/best-practices-for-ipfs-builders.md +++ b/docs/how-to/best-practices-for-ipfs-builders.md @@ -1,6 +1,6 @@ ---- -title: "Best practices for IPFS builders" -description: "Some IPFS features are disabled or not defaults, but we encourage their use under the right circumstances. We list them here for easy access by busy builders." +---title: Best practices for IPFS builders +description: Some IPFS features are disabled or not defaults, but we encourage their use under the right circumstances. We list them here for easy access by busy builders. +date: 2022-03-11 --- # Best practices for IPFS builders @@ -9,10 +9,9 @@ Some IPFS features are not enabled or set as defaults, but we encourage you to u ## Use CIDv1 for future-proof addressing and case-insenstive contexts -There are two versions of context identifiers (CIDs): CIDv0 and CIDv1. +There are two versions of CIDs (Content Identifiers), CIDv0 and CIDv1. -<<<<<<< HEAD:docs/how-to/best-practices-for-ipfs-builders -CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. You can quickly tell the difference between v0 and v1 CIDs since v0 CIDs always start with `Qm`. Many of the existing IPFS tools still generate CIDs in v0, for example: +CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. You can quickly tell the difference between v0 and v1 CIDs, because v0 CIDs always start with `Qm`. Many of the existing IPFS tools still generate CIDs in v0, for example: - [IPFS Desktop](http://docs.ipfs.io.ipns.localhost:8080/install/ipfs-desktop/#ipfs-desktop) - [/api/v0/add](https://docs.ipfs.io/reference/http/api/#api-v0-add), where the `cid-version` defaults to 0 unless an option that depends on CIDv1 is passed. @@ -34,47 +33,26 @@ ipfs add --cid-version 1 ``` To convert a CID from v0 to v1, see [CID conversion](https://docs.ipfs.io/concepts/content-addressing/#cid-conversion). -======= -CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. Many of the existing IPFS tools still generate CIDs in v0. You can quickly tell the difference between v0 and v1 CIDs since v0 CIDs always start with `Qm`. - - - -Some features use CIDv1 by default: - -- `files` ([Mutable File System](file-systems.md#mutable-file-system-mfs)) -- `object` operations - -We recommend you use CIDv1 when you want: - -- future-proof addressing -- case-insensitive addressing - -To opt in, use the `--cid-version` flag in the CLI: - -```shell -ipfs add --cid-version 1 -``` ->>>>>>> 8fde2e7cedefa409aaf55e475a88bec9675d99fd:docs/how-to/best-practices-for-ipfs-builders.md For more information on content addressing and CID versions, see [Content Addressing and CIDs](https://docs.ipfs.io/concepts/content-addressing/#content-addressing-and-cids). ## Enable pubsub if you need fast IPNS -<<<<<<< HEAD:docs/how-to/best-practices-for-ipfs-builders 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. -======= -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. Pubsub is an experimental feature and it should not be used in a production environment. It is disabled by default. ->>>>>>> 8fde2e7cedefa409aaf55e475a88bec9675d99fd:docs/how-to/best-practices-for-ipfs-builders.md -To use this feature, use the `--enable-pubsub-experiment` option when starting the IPFS daemon: +To use this feature, use `Ipns.UsePubsub` before starting the IPFS daemon: ```shell -ipfs --enable-pubsub-experiment +ipfs config --json Ipns.UsePubsub true +ipfs daemon ``` -See [IPFS pubsub](../reference/cli/#ipfs-pubsub) for more information on the available subcommands. +From this point on, IPNS will be resolved using both DHT and pubsub. Be mindful that this is still an experimental feature, with known limitations. See:  + +- [Experimental features > IPNS pubsub](https://github.com/ipfs/go-ipfs/blob/master/docs/experimental-features.md#ipns-pubsub) +- [Enable IPNS over pubsub by default, Issue 8591](https://github.com/ipfs/go-ipfs/issues/8591) -## Enable garbage collection if your data churn is expected to be high +## Enable Garbage Collection if your data churn is expected to be high Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called _garbage collection_. @@ -83,7 +61,7 @@ If you expect your data churn to be high, you may want to enable garbage collect However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. The following pages are useful for learning how pinning works: - [Persistence, permanence, and pinning](../concepts/persistence/#persistence-permanence-and-pinning) -- [Pinning in context](../concepts/persistence/#pinning-in-context) +- [Pinning in context](https://docs.ipfs.io/concepts/persistence/#pinning-in-context) - [Pin files using IPFS](./how-to/pin-files/#three-kinds-of-pins). Then you can safely enable garbage collection for all other data. See: @@ -98,11 +76,7 @@ To prevent one website from improperly accessing HTTP session data associated wi - subdomain gateway, or - DNSLink -<<<<<<< HEAD:docs/how-to/best-practices-for-ipfs-builders See: -======= -For more information on security and gateways, take a look at these pages: ->>>>>>> 8fde2e7cedefa409aaf55e475a88bec9675d99fd:docs/how-to/best-practices-for-ipfs-builders.md - [Violation of same-origin policy](../concepts/ipfs-gateway/#limitations-and-potential-workarounds) - [Subdomain gateway](./how-to/address-ipfs-on-web/#subdomain-gateway) From 3515445380226127ba2048b6a415c6e634728a60 Mon Sep 17 00:00:00 2001 From: Johnny <9611008+johnnymatthews@users.noreply.github.com> Date: Thu, 17 Mar 2022 13:17:28 -0400 Subject: [PATCH 5/8] Update docs/how-to/best-practices-for-ipfs-builders.md --- docs/how-to/best-practices-for-ipfs-builders.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/how-to/best-practices-for-ipfs-builders.md b/docs/how-to/best-practices-for-ipfs-builders.md index 015a23558..c4123ce35 100644 --- a/docs/how-to/best-practices-for-ipfs-builders.md +++ b/docs/how-to/best-practices-for-ipfs-builders.md @@ -1,4 +1,5 @@ ----title: Best practices for IPFS builders +--- +title: Best practices for IPFS builders description: Some IPFS features are disabled or not defaults, but we encourage their use under the right circumstances. We list them here for easy access by busy builders. date: 2022-03-11 --- From ce56d36a5ff46b39d8c0d551bb5e4de506ad3ff5 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 17 Mar 2022 18:50:51 +0100 Subject: [PATCH 6/8] chore: fix links --- .../how-to/best-practices-for-ipfs-builders.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/how-to/best-practices-for-ipfs-builders.md b/docs/how-to/best-practices-for-ipfs-builders.md index c4123ce35..809658c84 100644 --- a/docs/how-to/best-practices-for-ipfs-builders.md +++ b/docs/how-to/best-practices-for-ipfs-builders.md @@ -10,17 +10,17 @@ Some IPFS features are not enabled or set as defaults, but we encourage you to u ## Use CIDv1 for future-proof addressing and case-insenstive contexts -There are two versions of CIDs (Content Identifiers), CIDv0 and CIDv1. +There are two versions of CIDs ([Content Identifiers](../concepts/content-addressing/)), CIDv0 and CIDv1. CIDv0 is simpler but much less flexible than CIDv1. It doesn't offer the future-proof and case-insensitive addressing that CIDv1 offers. You can quickly tell the difference between v0 and v1 CIDs, because v0 CIDs always start with `Qm`. Many of the existing IPFS tools still generate CIDs in v0, for example: -- [IPFS Desktop](http://docs.ipfs.io.ipns.localhost:8080/install/ipfs-desktop/#ipfs-desktop) -- [/api/v0/add](https://docs.ipfs.io/reference/http/api/#api-v0-add), where the `cid-version` defaults to 0 unless an option that depends on CIDv1 is passed. +- [IPFS Desktop](../install/ipfs-desktop/#ipfs-desktop) +- [/api/v0/add](..//reference/http/api/#api-v0-add), where the `cid-version` defaults to 0 unless an option that depends on CIDv1 is passed. Some features use CIDv1 by default: - `files` ([Mutable File System](../concepts/file-systems/#mutable-file-system-mfs)) -- `object` operations ([ipfs object](https://docs.ipfs.io/reference/cli/#ipfs-object)) +- `dag` operations ([ipfs object](https://docs.ipfs.io/reference/cli/#ipfs-dag)) Use CIDv1 when you want: @@ -35,7 +35,7 @@ ipfs add --cid-version 1 To convert a CID from v0 to v1, see [CID conversion](https://docs.ipfs.io/concepts/content-addressing/#cid-conversion). -For more information on content addressing and CID versions, see [Content Addressing and CIDs](https://docs.ipfs.io/concepts/content-addressing/#content-addressing-and-cids). +For more information on content addressing and CID versions, see [Content Addressing and CIDs](../concepts/content-addressing/#content-addressing-and-cids). ## Enable pubsub if you need fast IPNS @@ -62,8 +62,8 @@ If you expect your data churn to be high, you may want to enable garbage collect However, you may also have data that you value. To make sure that you keep data that is valuable to you, pin the valued data. The following pages are useful for learning how pinning works: - [Persistence, permanence, and pinning](../concepts/persistence/#persistence-permanence-and-pinning) -- [Pinning in context](https://docs.ipfs.io/concepts/persistence/#pinning-in-context) -- [Pin files using IPFS](./how-to/pin-files/#three-kinds-of-pins). +- [Pinning in context](../concepts/persistence/#pinning-in-context) +- [Pin files using IPFS](../how-to/pin-files/#three-kinds-of-pins). Then you can safely enable garbage collection for all other data. See: @@ -80,5 +80,5 @@ To prevent one website from improperly accessing HTTP session data associated wi See: - [Violation of same-origin policy](../concepts/ipfs-gateway/#limitations-and-potential-workarounds) -- [Subdomain gateway](./how-to/address-ipfs-on-web/#subdomain-gateway) -- [DNSLink gateway](./how-to/address-ipfs-on-web/#http-gateways) +- [Subdomain gateway](../how-to/address-ipfs-on-web/#subdomain-gateway) +- [DNSLink gateway](../how-to/address-ipfs-on-web/#http-gateways) From 1d70efd14b1d44b400f96e3ffaf4f4ef7c497dd5 Mon Sep 17 00:00:00 2001 From: "jackson1.annemarie@gmail.com" Date: Fri, 18 Mar 2022 11:43:39 -0700 Subject: [PATCH 7/8] Clarifies pubsub use with ipns --- docs/how-to/best-practices-for-ipfs-builders.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/best-practices-for-ipfs-builders.md b/docs/how-to/best-practices-for-ipfs-builders.md index 015a23558..c2e61c437 100644 --- a/docs/how-to/best-practices-for-ipfs-builders.md +++ b/docs/how-to/best-practices-for-ipfs-builders.md @@ -36,9 +36,9 @@ To convert a CID from v0 to v1, see [CID conversion](https://docs.ipfs.io/concep For more information on content addressing and CID versions, see [Content Addressing and CIDs](https://docs.ipfs.io/concepts/content-addressing/#content-addressing-and-cids). -## Enable pubsub if you need fast IPNS +## Enable pubsub for 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. +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. To use this feature, use `Ipns.UsePubsub` before starting the IPFS daemon: @@ -47,7 +47,7 @@ ipfs config --json Ipns.UsePubsub true ipfs daemon ``` -From this point on, IPNS will be resolved using both DHT and pubsub. Be mindful that this is still an experimental feature, with known limitations. See:  +From this point on, IPNS will be resolved using both the `pubsub` and the DHT. Learn more about the limitations of this experimental feature here:  - [Experimental features > IPNS pubsub](https://github.com/ipfs/go-ipfs/blob/master/docs/experimental-features.md#ipns-pubsub) - [Enable IPNS over pubsub by default, Issue 8591](https://github.com/ipfs/go-ipfs/issues/8591) From e508011808b550b856bf742940e53c42a1afcc8b Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 23 Mar 2022 00:58:03 +0100 Subject: [PATCH 8/8] Simplify pubsub description --- docs/how-to/best-practices-for-ipfs-builders.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/best-practices-for-ipfs-builders.md b/docs/how-to/best-practices-for-ipfs-builders.md index 40f7598be..9dc5e34cc 100644 --- a/docs/how-to/best-practices-for-ipfs-builders.md +++ b/docs/how-to/best-practices-for-ipfs-builders.md @@ -39,7 +39,7 @@ For more information on content addressing and CID versions, see [Content Addres ## 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. +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. Pubsub is an experimental feature, so use it with care. It's disabled by default. To use this feature, use `Ipns.UsePubsub` before starting the IPFS daemon: