From 3330e49136b80f47965864e2b483eac90228bd7a Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Mon, 15 Mar 2021 15:45:24 +1100 Subject: [PATCH 1/6] add typescript proposal --- proposals/79-typescript-definitions.md | 54 ++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 proposals/79-typescript-definitions.md diff --git a/proposals/79-typescript-definitions.md b/proposals/79-typescript-definitions.md new file mode 100644 index 00000000..5f17b630 --- /dev/null +++ b/proposals/79-typescript-definitions.md @@ -0,0 +1,54 @@ +# TypeScript Definitions for core libraries + +Authors: @rvagg + +Initial PR: https://github.com/protocol/web3-dev-team/pull/79 + +## Purpose & impact + +Consumers of our JavaScript libraries & components should have sufficient TypeScript definitions, available through standard means, to write fully typed TypeScript code, or use that code to drive tooling that consumes these definitions - such as VS Code editing enhancements, documentation production pipelines, type checking tooling for test & CI pipelines. + +This work is high-value and high-impact for the JavaScript ecosystem and those of us working on open source JavaScript libraries can all provide anecdotal evidence for the frequency with which developers request better TypeScript annotations for our libraries. The rate of TypeScript adoption, particularly within larger-scale projects, is increasing, but TypeScript definitions are increasingly useful as they are included in general JavaScript linting, checking and documentation tooling. + +This work provides high-leverage within our suite of JavaScript tools as we mature, refactor, modularize and create. We are already establishing a suite of practices and tooling that are used in varying ways across PL JavaScript projects that use definitions, even though we have very few TypeScript projects throughout our GitHub orgs ( being a rare example, which was initially contributed by Textile). It is reasonable to expect that the majority of new JavaScript code produced by Protocol Labs into the future will make use of TypeScript annotations in some way. + +Work on this effort has been largely completed, thanks primarily to @hugomrdias, @Gozala, and @achingbrain with assistance from the entire JavaScript team in various ways. The bulk of the activity has been tracked as a roll-up in to js-ipfs @ . + +Remaining work to integrate the current set of js-ipfs dependencies into js-ipfs and address the typing for code directly in js-ipfs is happening here: https://github.com/ipfs/js-ipfs/pull/3550 + +Aside from completing the remaining js-ipfs itegration work, the scope of this project includes some additional libraries that re not currently part of the js-ipfs dependency tree, including: + + * Next-generation IPLD codec libraries (using the js-multiformats pattern) + * _TODO: what other non-archived, non-dormant project should we include here to achieve the above value & impact ideals?_ + +Project-specific decisions will be made regarding the depth of TypeScript definitional work. Projects with greater expected future usage should include full type checking in CI and will therefore require basic inline TypeScript annotations. Projects that are dependencies but are not expected to be actively maintained or developed further into the future may just include basic API type definitions so that dependents can make use of those. + + From fa1cb42b09826d1df690566c473fdfd7bd99c644 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Tue, 16 Mar 2021 18:09:11 +1100 Subject: [PATCH 2/6] Update proposals/79-typescript-definitions.md Co-authored-by: Jacob Heun --- proposals/79-typescript-definitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/79-typescript-definitions.md b/proposals/79-typescript-definitions.md index 5f17b630..5729dd48 100644 --- a/proposals/79-typescript-definitions.md +++ b/proposals/79-typescript-definitions.md @@ -16,7 +16,7 @@ Work on this effort has been largely completed, thanks primarily to @hugomrdias, Remaining work to integrate the current set of js-ipfs dependencies into js-ipfs and address the typing for code directly in js-ipfs is happening here: https://github.com/ipfs/js-ipfs/pull/3550 -Aside from completing the remaining js-ipfs itegration work, the scope of this project includes some additional libraries that re not currently part of the js-ipfs dependency tree, including: +Aside from completing the remaining js-ipfs integration work, the scope of this project includes some additional libraries that are not currently part of the js-ipfs dependency tree, including: * Next-generation IPLD codec libraries (using the js-multiformats pattern) * _TODO: what other non-archived, non-dormant project should we include here to achieve the above value & impact ideals?_ From 6624cfa8119450a7e88a7501953ba60cf91044cd Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Tue, 16 Mar 2021 18:11:38 +1100 Subject: [PATCH 3/6] Update proposals/79-typescript-definitions.md Co-authored-by: Vasco Santos --- proposals/79-typescript-definitions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/79-typescript-definitions.md b/proposals/79-typescript-definitions.md index 5729dd48..8d1199e9 100644 --- a/proposals/79-typescript-definitions.md +++ b/proposals/79-typescript-definitions.md @@ -19,6 +19,7 @@ Remaining work to integrate the current set of js-ipfs dependencies into js-ipfs Aside from completing the remaining js-ipfs integration work, the scope of this project includes some additional libraries that are not currently part of the js-ipfs dependency tree, including: * Next-generation IPLD codec libraries (using the js-multiformats pattern) + * js-libp2p core types had a first iteration, but there are a few gaps that should be addressed, specially in the configuration, [as follow up](https://github.com/libp2p/js-libp2p/issues/830). There is also a general libp2p typescript [tracking](https://github.com/libp2p/js-libp2p/issues/659) with all the libp2p modules, but these do not seem high priority at the moment, as most users typically only interact with the core API. * _TODO: what other non-archived, non-dormant project should we include here to achieve the above value & impact ideals?_ Project-specific decisions will be made regarding the depth of TypeScript definitional work. Projects with greater expected future usage should include full type checking in CI and will therefore require basic inline TypeScript annotations. Projects that are dependencies but are not expected to be actively maintained or developed further into the future may just include basic API type definitions so that dependents can make use of those. From f0bc4c540b93c773d8d3a1295ce38580846f00a4 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Tue, 16 Mar 2021 18:12:59 +1100 Subject: [PATCH 4/6] Update 79-typescript-definitions.md --- proposals/79-typescript-definitions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/79-typescript-definitions.md b/proposals/79-typescript-definitions.md index 8d1199e9..83272575 100644 --- a/proposals/79-typescript-definitions.md +++ b/proposals/79-typescript-definitions.md @@ -19,6 +19,7 @@ Remaining work to integrate the current set of js-ipfs dependencies into js-ipfs Aside from completing the remaining js-ipfs integration work, the scope of this project includes some additional libraries that are not currently part of the js-ipfs dependency tree, including: * Next-generation IPLD codec libraries (using the js-multiformats pattern) + * [js-multiformats legacy interface](https://github.com/multiformats/js-multiformats/issues/67) * js-libp2p core types had a first iteration, but there are a few gaps that should be addressed, specially in the configuration, [as follow up](https://github.com/libp2p/js-libp2p/issues/830). There is also a general libp2p typescript [tracking](https://github.com/libp2p/js-libp2p/issues/659) with all the libp2p modules, but these do not seem high priority at the moment, as most users typically only interact with the core API. * _TODO: what other non-archived, non-dormant project should we include here to achieve the above value & impact ideals?_ From f1e6f2ecd809802eed319cd9f3433dbf3b81f704 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Mon, 22 Mar 2021 13:49:09 +1100 Subject: [PATCH 5/6] tighten scope --- proposals/79-typescript-definitions.md | 49 ++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 6 deletions(-) diff --git a/proposals/79-typescript-definitions.md b/proposals/79-typescript-definitions.md index 83272575..3912d3a9 100644 --- a/proposals/79-typescript-definitions.md +++ b/proposals/79-typescript-definitions.md @@ -19,13 +19,17 @@ Remaining work to integrate the current set of js-ipfs dependencies into js-ipfs Aside from completing the remaining js-ipfs integration work, the scope of this project includes some additional libraries that are not currently part of the js-ipfs dependency tree, including: * Next-generation IPLD codec libraries (using the js-multiformats pattern) - * [js-multiformats legacy interface](https://github.com/multiformats/js-multiformats/issues/67) - * js-libp2p core types had a first iteration, but there are a few gaps that should be addressed, specially in the configuration, [as follow up](https://github.com/libp2p/js-libp2p/issues/830). There is also a general libp2p typescript [tracking](https://github.com/libp2p/js-libp2p/issues/659) with all the libp2p modules, but these do not seem high priority at the moment, as most users typically only interact with the core API. - * _TODO: what other non-archived, non-dormant project should we include here to achieve the above value & impact ideals?_ + * [js-multiformats legacy interface](https://github.com/multiformats/js-multiformats/issues/67) needs updating to match the newly exported js-ipfs/js-ipld types. + * [js-multiaddr](https://github.com/multiformats/js-multiaddr/pull/159) is mostly done, but needs to be a non-breaking change to land + * js-libp2p core types had a first iteration, but there are a few gaps that should be addressed, specially in the configuration, [as follow up](https://github.com/libp2p/js-libp2p/issues/830). + * _Scope:_ the priority for js-libp2p is in the generally exported API, so direct users of js-libp2p have types for that interface. + * _Out of scope for this project:_ there is also a general libp2p typescript [tracking](https://github.com/libp2p/js-libp2p/issues/659) with all the libp2p modules, but these do not appaer to be high priority at the moment, as most users typically only interact with the core API. -Project-specific decisions will be made regarding the depth of TypeScript definitional work. Projects with greater expected future usage should include full type checking in CI and will therefore require basic inline TypeScript annotations. Projects that are dependencies but are not expected to be actively maintained or developed further into the future may just include basic API type definitions so that dependents can make use of those. +During execution of this project, where questions of scope arise that are not covered above, library-specific decisions will be made regarding the depth of TypeScript definitional work using the following criteria: + * Projects with greater expected future usage should include full type checking in CI and will therefore require basic inline TypeScript annotations. + * Projects that are dependencies but are not expected to be actively maintained or developed further into the future may just include basic API type definitions so that dependents can make use of those. + * Any work estimated to be consisting of more than 2 days for 1 FTE will be either scoped as a separate project (or bundled into another, existing project, collecting future work), or be brought back to [the PR for this proposal](https://github.com/protocol/web3-dev-team/pull/79) for further discussion of expansion of scope. - + +* JavaScript +* TypeScript +* js-ipfs/ipld/libp2p and related stack expertise From 9c2e6e997198d17c7ff8427b17c0bdbef389d138 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Mon, 29 Mar 2021 15:15:49 +1100 Subject: [PATCH 6/6] notes for: IPLD, impact, success metric --- proposals/79-typescript-definitions.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/proposals/79-typescript-definitions.md b/proposals/79-typescript-definitions.md index 3912d3a9..0c1a7b25 100644 --- a/proposals/79-typescript-definitions.md +++ b/proposals/79-typescript-definitions.md @@ -25,6 +25,10 @@ Aside from completing the remaining js-ipfs integration work, the scope of this * _Scope:_ the priority for js-libp2p is in the generally exported API, so direct users of js-libp2p have types for that interface. * _Out of scope for this project:_ there is also a general libp2p typescript [tracking](https://github.com/libp2p/js-libp2p/issues/659) with all the libp2p modules, but these do not appaer to be high priority at the moment, as most users typically only interact with the core API. +Currently the next-generation IPLD codecs and js-multiformats do not contribute directly to other parts of the JS stack (js-ipfs most notably), however: + * There is ongoing [work to integrate these into the js-ipfs stack](https://github.com/ipfs/js-ipfs-unixfs/pull/116) due to a desire to retire old components. Incomplete typing on these new components will be a blocker for easier integration. + * Our ecosystem is already consuming these newer components - in particular we advise all new codec development to consume the js-multiformats pattern ([e.g.](https://github.com/ceramicnetwork/js-dag-jose/)), much of which uses TypeScript. + During execution of this project, where questions of scope arise that are not covered above, library-specific decisions will be made regarding the depth of TypeScript definitional work using the following criteria: * Projects with greater expected future usage should include full type checking in CI and will therefore require basic inline TypeScript annotations. * Projects that are dependencies but are not expected to be actively maintained or developed further into the future may just include basic API type definitions so that dependents can make use of those. @@ -50,6 +54,8 @@ We have some existing TypeScript in the PL suite of JavaScript. This may expand We already have [one example](https://github.com/ipfs/js-dag-service) of code being contributed to the PL stack from a third-party that uses TypeScript and could be improved by typing in the rest of our stack. +Work on typing in the js-ipfs stack has already surfaced a large number of bugs. Typing on complex codebases is a proven method of increasing code quality, both in the codebase and by consumers of the codebases. + #### Confidence _How sure are we that this impact would be realized? Label from [this scale](https://medium.com/@nimay/inside-product-introduction-to-feature-priority-using-ice-impact-confidence-ease-and-gist-5180434e5b15)_. @@ -60,7 +66,12 @@ _How sure are we that this impact would be realized? Label from [this scale](htt #### What does done look like? _What specific deliverables should completed to consider this project done?_ -See Scope description above. +By identifying a small number of key downstream projects that consume our libraries and also use TypeScript and counting the use of `@ts-ignore` annotations that exist to deal with lack of exported typing from our libraries we have a metric for degree of success. + +* https://github.com/ceramicnetwork/js-ceramic - contains a considerable number of `@ts-ignore` statements that relate to js-ipfs +* https://github.com/ceramicnetwork/js-dag-jose - is currently unable to consume js-multiformats to properly execute its test suite + +Also see Scope description above. #### What does success look like? _Success means impact. How will we know we did the right thing?_