2023/2024 Contributor Hospitality Ideas

BigLep commented 1 year ago

Below are items that stuck out when coming to https://github.com/ipfs/helia with fresh eyes imagining what it's like for someone who hears about Helia, wants to learn more, and wants to contribute potentially:

README Items

[x] Reference helia-unixfs, helia-ipns, etc. We don't give pointers to these important modules. https://github.com/ipfs/helia/pull/76
[x] How do I get started as a consumer? Reference https://github.com/ipfs-examples/helia-examples
[x] Reference demo-slides, recordings, etc: https://github.com/ipfs/helia/pull/80
[x] Remove erroneous verbiage: "The core of IPFS is the Files API, which will likewise be implemented in Helia. These initial building blocks are in development now; have a look at this repo's PR(s)." Is this true. Isn't this in helia-unixfs?
[x] @whizzzkid : Fix API docs links: https://github.com/ipfs/aegir/pull/1228
[x] Link to code coverage. The badge lists it as unknown. This is a new endeavor. We should be able to show off good numbers to start. https://github.com/ipfs/aegir/pull/1195
[x] @BigLep Have a section about who some of our users are. I expect we don't have any currently. That's ok, but lets solicit for people to share us. We want a "your logo here": https://github.com/ipfs/helia/pull/83
[x] @BigLep Update project status section: https://github.com/ipfs/helia/pull/83
[x] Answer "Where should a user ask questions?"
[x] @achingbrain Answer "What is the relationship of this project to js-ipfs?"
[x] @achingbrain Answer "How do we prove interoperability with other IPFS implementations like Kubo?"
[x] @achingbrain Answer "How does it perform compared to other implementations including js-ipfs?"
[ ] Answer "What runtimes do we support (node versions, browser distributions/versions including mobile/desktop)"
[ ] I think we could use more visuals on the readme. I think having something visual showing the relationship between ipfs/helia, js-libp2p, and the other Helia repos. I think seeing this helps drive home the point that Helia is modular.

Manifesto Items

[ ] @achingbrain "The core of Helia will be very focused on use as a library: just js-libp2p, a blockstore, js-bitswap and a POSIX-like API which will be extendable to add additional features such as IPNS, an RPC-API, etc." and " instead it will present an abstraction of posix filesystem operations (ls, cat, etc) as an API but the underlying filesystem(s) will be configurable." The POSIX-like API is no longer part of it right?
[ ] @achingbrain Permissions discussion should probably have a callout that this is for when Helia is run as a daemon, but that isn't the primary usecase.

Other specific things to do

[x] @whizzzkid: Add CODEOWNERS to the helia repos (helia, helia-unixfs, hela-ipns, helia-examples) to make it clear who is responsible for reviewing: https://github.com/ipfs/helia/pull/78
[x] @whizzzkid: Have helia-examples provide a landing page of an overview of the options: https://github.com/ipfs-examples/helia-examples/pull/27
[x] @whizzzkid: helia/packages READMEs should have minimal text but instead drive back to https://github.com/ipfs/helia which has a lot more content.
[x] (similar to previous) helia-ipns and helia-unixfs READMEs should be as minimal as possible and drive to https://github.com/ipfs/helia to learn about contributing, etc.
[ ] @achingbrain : Have a tracking issue of what needs to specifically be done before we can shut down js-ipfs from a maintenance regard.
[ ] @achingbrain / @BigLep : I know we have the roadmap doc (https://github.com/ipfs/helia/blob/main/ROADMAP.md ). Given it's been a few months, we should update with current understanding.
[ ] https://github.com/ipfs/helia/issues/81
[ ] https://github.com/ipfs/helia/issues/82

General thoughts

Provide more bite-size chunks for would-be contributors to pick off. As of 2023-02-20, we basically have a really large contribution in https://github.com/ipfs/helia/issues/28 or we have smaller things in examples which is great but it could be clarified with a prioritized list of examples. It would be useful to get other work items scoped out with clear done criteria and likely some labeling to make clear the sizing.
I'm curious how useful people find the Helia API docs we link to. It seems like to do much, need to the unixfs repo for example. Does it make sense to generate all the Helia-related projects docs together so it's clearer to a user what are all the Helia APIs are exposed?
I think our tagline needs to be more than "An implementation of IPFS in JavaScript". I think the statement down below is more compelling "A lean, modular, and modern implementation of IPFS for the prolific JS and browser environments.".

whizzzkid commented 1 year ago

Summarizing Tasks:

[x] Reference helia-unixfs, helia-ipns, etc.
- https://github.com/ipfs/helia/pull/76
[ ] Reference helia-examples
- https://github.com/ipfs-examples/helia-examples/pull/27
[x] Reference demo-slides, recordings, etc
- https://github.com/ipfs/helia/pull/80
[ ] Fix API docs links
- https://github.com/ipfs/aegir/pull/1228
[ ] Fix Code coverage
- https://github.com/ipfs/aegir/pull/1195
[ ] Fix NPM docs and link backs.
- https://github.com/ipfs/aegir/pull/1228
[ ] Fix roadmap items with current items (@achingbrain)
[ ] Fix manifest language (@achingbrain)
[ ] Add benchmark comparisons against js-ipfs or other implementations (@achingbrain)
[x] Add CODEOWNERS
- https://github.com/ipfs/helia/pull/78

achingbrain commented 1 year ago

NPM docs like don't link back to the top-level helia REAME which has all the info (see npmjs.com/package/helia ). The API links from within are broken.

I think a more fleshed out Documentation section in each package would be good here? Something similar to the version in the helia examples.

BigLep commented 1 year ago

I'm going to finetune this but here are some things coming to mind when looking at this again with fresh eyes. I know I need to check in on the other comments above. I'm still working here but wanted to get out some initial notes that was seeing.

What runtimes do we support (node versions, browser distributions/versions including mobile/desktop)
https://github.com/ipfs/helia/issues/81
https://github.com/ipfs/helia/issues/82
It would be great to have a section about who some of our users are. I expect we don't have any currently. That's ok, but lets solicit for people to share us. We want a "your logo here".
I think we could use more visuals on the readme. I think having something visual showing the relationship between ipfs/helia, js-libp2p, and the other Helia repos. I think seeing this helps drive home the point that Helia is modular.
I'm curious how useful people find the Helia API docs we link to. It seems like to do much, need to the unixfs repo for example. Does it make sense to generate all the Helia-related projects docs together so it's clearer to a user what are all the Helia APIs are exposed?
I think our tagline needs to be more than "An implementation of IPFS in JavaScript". I think the statement down below is more compelling "A lean, modular, and modern implementation of IPFS for the prolific JS and browser environments.".
Have the bare minimum text under each of the packages under https://github.com/ipfs/helia/tree/main/packages aggressively link back to https://github.com/ipfs/helia. (I assume we still need to keep the licensing text copy/pasted, but stuff about contributing should all be one place.). This prevents copy/paste and helps extract more value out of the work we're putting into the top-level project readme.
Project status section needs to be updated.

BigLep commented 1 year ago

@achingbrain :

NPM docs like don't link back to the top-level helia REAME which has all the info (see npmjs.com/package/helia ). The API links from within are broken.

The point I'm trying to make is that we're going to invest a lot in https://github.com/ipfs/helia. That is the landing page. I think we should have the bare minimum text under each of the packages under https://github.com/ipfs/helia/tree/main/packages by provide a big/bold link back to https://github.com/ipfs/helia. (I assume we still need to keep the licensing text copy/pasted, but stuff about contributing, docs, support, etc. should all be in one place.). This prevents copy/paste and helps extract more value out of the work we're putting into the top-level project readme. Does that make sense?

BigLep commented 1 year ago

I did some more readme updates for some of the items above: https://github.com/ipfs/helia/pull/83

BigLep commented 1 year ago

Thanks @whizzzkid for your contributions here and getting more task tracking going. I know I piled some more tasks on with some of my comments. I have gone through and attempted to coalese all the tasks in the top-level issue description. Feel free to modify. We can let that be our source of truth for how this endeavor is progressing.

BigLep commented 1 year ago

I think there are two tiers of work. There are easier things that can be completed pretty independently. Thanks for seeing and jumping on those @whizzzkid. Please keep plugging away as able.

Then there are the bigger items around the project's relationship to other projects and direction. I think this is the most important area to focus on @achingbrain . This is items like the manifest updates and describing how the project relates to js-ipfs. I want someone to come to the project and after a quick read to get why we're building Helia and where it fits. I would then role to the developer/contributor guide stuff. Let me know if it's helpful to talk more specifically on priorities here.

ipfs / helia