search

ipfs / js-ipfs

IPFS implementation in JavaScript
https://js.ipfs.tech
Other
7.43k stars 1.25k forks source link

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

Closed BigLep closed 7 months ago

BigLep commented 1 year ago

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:

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:

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 (non issue handling)
- [x] Define all the steps for the deprecation (@biglep to sign off)
- [x] List out the npm modules to deprecate (everything that corresponds to js-ipfs/packages)
- [x] List out the READMEs to update (everything under js-ipfs/packages)
- [x] @achingbrain Generate "deprecation notice" text for npm modules
- [x] @achingbrain Generate "deprecation notice" text for READMEs
- [x] @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)
- [x] https://github.com/ipfs/helia/issues/121
- [x] https://github.com/ipfs/helia/issues/122
- [ ] https://github.com/ipfs/helia/issues/120
- [x] Fill in the TODOs in this issue
### Preparation Tasks: issue handling (ECD 2023-05-24)
- [x] Create project board and add all issues: https://github.com/orgs/ipfs/projects/26/views/1
- [x] @SgtPooki Assign owners (via assignee field in GitHub) for issues
- [x] Document the issue handling process: https://pl-strflt.notion.site/2023Q2-js-ipfs-Deprecation-c84d5d4f661044198ba6e63bf0a34790
- [x] Create necessary labels for issue/PR handling
- [x] Create issue messaging
### Disruption Eve (ECD 2023-05-25)
- [x] Create a discuss.ipfs.tech post for wider visibility: https://github.com/ipfs/ipfs-blog/pull/585
- [ ] ~Deter js-ipfs issue creation~
### Disruption Tasks: README updates and npm module deprecation (ECD 2023-05-25)
- [x] README updates (single PR for all READMEs under js-ipfs/packages) - https://github.com/ipfs/js-ipfs/pull/4362
- [x] interface-ipfs-core
- [x] ipfs-cli
- [x] ipfs-client
- [x] ipfs-core-config
- [x] ipfs-core-types
- [x] ipfs-core-utils
- [x] ipfs-core
- [x] ipfs-daemon
- [x] ipfs-grpc-client
- [x] ipfs-grpc-protocol
- [x] ipfs-grpc-server
- [x] ipfs-http-client
- [x] ipfs-http-gateway
- [x] ipfs-http-response
- [x] ipfs-http-server
- [x] ipfs-message-port-client
- [x] ipfs-message-port-protocol
- [x] ipfs-message-port-server
- [x] ipfs
### Disruption Tasks: issues and PRs so can archive the repo
- [x] handle open PRs
- [x] (ECD 2023-05-31) First pass of triage and responding to all [open issues](https://github.com/orgs/ipfs/projects/26) by following [the process here](https://www.notion.so/pl-strflt/2023Q2-js-ipfs-Deprecation-c84d5d4f661044198ba6e63bf0a34790?pvs=4#61d0f1ff8acc4bf2bf27eb549b9e9b65).
- [x] (ECD 2023-06-07) Wait a week to see what issues get reopened
- [x] (ECD 2023-06-09) Close out reopened issues
### Wrap up tasks
- [x] Blog entry about the deprecation
- [x] Archive the repo - at this point no more issues can be created or altered
- [x] Update docs.ipfs.tech: https://github.com/ipfs/ipfs-docs/issues/1611
- [x] Handle js.ipfs.io: https://github.com/ipfs/js.ipfs.tech/issues/316
- [ ] Protoschool: https://github.com/ProtoSchool/protoschool.github.io/issues/874
- [x] Close this issue
SgtPooki commented 1 year ago

related: https://github.com/ipfs/ipfs-gui/issues/107 & https://github.com/ipfs/ipld-explorer-components/issues/359

SgtPooki commented 1 year ago

I talked to @RangerMauve about migration to helia and it sounds like https://github.com/libp2p/js-libp2p/issues/1461 is a blocker

SgtPooki commented 1 year ago

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 https://github.com/ipfs/ipld-explorer-components/issues/359 & ipfs-share
  4. Closing/migrating all js-ipfs issues with pointer to migration guide & helia

something I thought of during our talk:

  1. 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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

Given no issues have been reopened over a week per https://github.com/ipfs/js-ipfs/issues/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 commented 7 months ago

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.