[Tracking Issue] js-ipfs deprecation - signposting over to Helia

[BigLep]

Info for js-ipfs users affected by the deprecation

About

As shared back in 202310 in https://blog.ipfs.tech/state-of-ipfs-in-js/, the current maintainers of js-ipfs (Protocol Labs’ EngRes (Engineering & Research) group), have been active in developing Helia. Now that v1 of Helia has been released, the intent is to signpost from js-ipfs to Helia and ultimately archive the repo. The specific steps and timeline for this are below. This issue was originally created as a placeholder to start adding notes as things come up and cross-linking issues, and now it serves as the deprecation project tracker.

FAQ

Scope: what is being deprecated?

js-ipfs and all the modules that live in this monorepo.

Key dependencies of js-ipfs like js-libp2p and js-bitswap ARE NOT being deprecated - they are critical dependencies of Helia as well.

Why is js-ipfs being deprecated?

The current maintainers don't have bandwidth to maintain Helia and js-ipfs. Helis takes the lessons learned from the years developing and supporting js-ipfs and we believe provides a better user and maintainer experience.

More details are covered in:

• Hello Helia talk at IPFS Thing 2023
• The State of IPFS in JS 202210 blog entry
• Helia Manifest

How do I migrate to Helia from js-ipfs?

We have created a migration guide at https://github.com/ipfs/helia/wiki/Migrating-from-js-IPFS . If you have any questions or issues with it, please open a Helia issue.

How do I learn more about Helia?

Please see the README and other docs linked from the Helia repo. helia-examples are also a great way to see Helia in action.

How do I stay updated on this deprecation?

This is the deprecation tracking issue. As items are completed, we'll update the task lists here. We'll also post major updates as comments in the issue.

What is the expected timeline of this deprecation?

See the "Expected Completed Dates" (ECD) for the various task lists or tasks below. We are generally aiming to complete the bulk of this by mid-June. "Disruption" will start happening ~2023-05-24. Per below, we'll leave a time for users to reopen any issues or PRs that they feel were closed in error.

What if I have more comments on a closed issue or PR?

Per above, we are going to be archiving this repo which will prevent further updates to issues and PRs. That said, before then we'll give a week for someone to reopen any issue or PR that we close in case they have followup questions or concerns. We'll engage with any of these reopened issues before archiving the repo. We expect this will be during or shortly after this one-week response window, but this will be dependent on how many issues get reopened and how long it takes us to process them.

Can I volunteer to take over the maintainership of js-ipfs?

If someone doesn't want to move over to Helia and instead take over maintaining js-ipfs, they are welcome to fork this repo and notify in this issue. @ipfs/helia-dev can update the ipfs/js-ipfs repo readme to point to your fork. Note that npm modules will stay deprecated to prevent any security exposure for users.

The js-ipfs repo has a treasure trove of history and discussion about js-ipfs and IPFS in JS in general. Are there any critical takeaways from the deprecation process?

While not exhaustive, below are some issues that were particularly rich as we went through and closed the 300+ open issues:

• Let's understand who is using js-ipfs! #2359
• A viable alternative to go-ipfs? #1563
• Achieving Connectivity Magic #1459
• Embedded JS-IPFS in Brave (experiment) ipfs-companion#716
• Notes on building and manipulating large IPLD graphs in JavaScript and LevelDB. #1416

Info for js-ipfs maintainers executing this deprecation

Deprecation Tasks

Below are the set of tasks for completing this deprecation. They are broken into different lists.

• Preparation tasks are items that maintainers are doing to ensure our ducks are in a row before we start disrupting users with this change.
• Disruption tasks cause messages to be sent to users, issues to be closed, modules archived, etc.

Preparation Tasks (non issue handling)

Beta Give feedback

1. Define all the steps for the deprecation (@BigLep to sign off)
2. List out the npm modules to deprecate (everything that corresponds to js-ipfs/packages)
3. List out the READMEs to update (everything under js-ipfs/packages)
4. @achingbrain Generate "deprecation notice" text for npm modules
5. @achingbrain Generate "deprecation notice" text for READMEs
6. @achingbrain Generate "deprecation notice" text for discuss.ipfs.tech

Preparation Tasks: coding/docs items important before driving more energy to Helia (ECD 2023-05-24)

Beta Give feedback

1. Provide a default libp2p instance helia#121
   released +1
2. Helia identifies itself to the network helia#122
   released +1
3. @biglep 202305 feedback on Migration Guide and FAQ helia#120
   topic/docs +1
   
4. Fill in the TODOs in this issue

Preparation Tasks: issue handling (ECD 2023-05-24)

Beta Give feedback

1. Create project board and add all issues: https://github.com/orgs/ipfs/projects/26/views/1
2. @SgtPooki Assign owners (via assignee field in GitHub) for issues
3. Document the issue handling process: https://pl-strflt.notion.site/2023Q2-js-ipfs-Deprecation-c84d5d4f661044198ba6e63bf0a34790
4. Create necessary labels for issue/PR handling
5. Create issue messaging

Disruption Eve (ECD 2023-05-25)

Beta Give feedback

1. Create a discuss.ipfs.tech post for wider visibility: js-ipfs deprecation - replaced by Helia ipfs-blog#585
2. Deter js-ipfs issue creation

Disruption Tasks: README updates and npm module deprecation (ECD 2023-05-25)

Beta Give feedback

1. README updates (single PR for all READMEs under js-ipfs/packages) - docs: add deprecation notice to readmes #4362
2. interface-ipfs-core
3. ipfs-cli
4. ipfs-client
5. ipfs-core-config
6. ipfs-core-types
7. ipfs-core-utils
8. ipfs-core
9. ipfs-daemon
10. ipfs-grpc-client
11. ipfs-grpc-protocol
12. ipfs-grpc-server
13. ipfs-http-client
14. ipfs-http-gateway
15. ipfs-http-response
16. ipfs-http-server
17. ipfs-message-port-client
18. ipfs-message-port-protocol
19. ipfs-message-port-server
20. ipfs

Disruption Tasks: issues and PRs so can archive the repo

Beta Give feedback

1. handle open PRs
2. (ECD 2023-05-31) First pass of triage and responding to all open issues by following the process here.
3. (ECD 2023-06-07) Wait a week to see what issues get reopened
4. (ECD 2023-06-09) Close out reopened issues

Wrap up tasks

Beta Give feedback

1. Blog entry about the deprecation
2. Archive the repo - at this point no more issues can be created or altered
3. Update docs.ipfs.tech: Catalog and figure out what to do with js-ipfs content ipfs-docs#1611
4. Handle js.ipfs.io: Update in light of Helia release and js-ipfs deprecation ipfs-inactive/old-js-ipfs-website#316
5. Protoschool: Update to use Helia instead of deprecated js-ipfs ProtoSchool/protoschool.github.io#874
6. Close this issue

[SgtPooki]

related: ipfs/ipfs-gui#107 & ipfs/ipld-explorer-components#359

[SgtPooki]

I talked to @RangerMauve about migration to helia and it sounds like libp2p/js-libp2p#1461 is a blocker

[SgtPooki]

Chatting with @achingbrain about rough requirements/plan for migration

1. Notes in all the readmes.
2. deprecation notes on NPM, (all packages inside js-ipfs repo)
   • deprecate ipfs-utils
3. migration guide
   • "I used to use these APIs with js-ipfs, but now i use these with helia like this" - for all happypath
     • We would add sections for specific non-happypath cases, or "case-studies" where we've migrated old tooling (like ipld-explorer-components and ipfs-share, etc.)
   • @SgtPooki - Use notion doc for documenting specific usecases while working on js-ipfs deprecation for feat: remove dependency on js-ipfs ipld-explorer-components#359 & ipfs-share
4. Closing/migrating all js-ipfs issues with pointer to migration guide & helia

something I thought of during our talk:

4. boilerplate messages for js-ipfs issue closing/cleanup
   • One message for issues that should check if helia solves their problems
   • Message for issues that definitely have solutions in helia
   • Message for unsupported things where users may be better suited to use js-kubo-rpc-client instead of helia

[BigLep]

Some updates on preparing for the deprecation:

1. The issue has been updated with more thorough task lists.
2. A project board has been created (https://github.com/orgs/ipfs/projects/26 ) to track the handling of the open issues in js-ipfs.
3. The deprecation process and messaging is all being drafted in https://pl-strflt.notion.site/2023Q2-js-ipfs-Deprecation-c84d5d4f661044198ba6e63bf0a34790 (to allow for easier commenting)

[BigLep]

2023-05-23 update: we're getting close to doing the disruption phase. Some updates:

1. This issue itself had some updates with more text filled in, tasks rearranged, and expected completion dates added.
2. The issue handling process and messaging has had various updates: https://pl-strflt.notion.site/2023Q2-js-ipfs-Deprecation-c84d5d4f661044198ba6e63bf0a34790

[BigLep]

2023-05-24 update: we have completed all the "preparation tasks" and will start in on the "disruption tasks". The team has the goal of making it through the 300+ js-ipfs issues and PRs by end of week (2023-05-26).

[BigLep]

Per https://github.com/orgs/ipfs/projects/26/views/2, 372 issues and/PRs have been closed. There is one open item :). We'll sweep back through on 2023-06-08 to see if any issues have reopened. If there aren't any, we'll move forward with repo archiving.

[BigLep]

Given no issues have been reopened over a week per #4336 , I'm going to archive this issue. That will prevent this issue from being mutated. We have tracking items for the relevant documentation items. When those are all done, we'll come back, unarchive the repo, and close this last issue.

Thanks all for your work and support in making this effort happen. Well done.

[BigLep]

I'm closing this issue now that the docs issues were completed. The only thing that wasn't done was around proto.school, but dealing with messaging about the outdated nature of that overall site is a separate endeavor.