Polkadot-JS: Moving Forward
Table of Contents
Summary
Over the past few years, the Polkadot ecosystem has thrived with critical support from libraries under the @polkadot namespace. Predominantly developed by a single individual, Jaco, these libraries serve as the backbone for external interactions with the Polkadot network. This blog post outlines how, with the support of my teammates on the front team (tools) and the community, I aim to take on a share of the responsibility for maintaining Polkadot-JS, increasing its bus factor and ensuring its continued stability and operation as Polkadot continues to evolve.
Intro About Myself
I am a Software Engineer at Parity with a focus on building and maintaining tools for both internal and external purposes. For over three years, I’ve contributed to projects like Substrate-api-sidecar, Asset-Transfer-Api, and Txwrapper-core, all relying on the Polkadot-JS framework. This hands-on experience has positioned me as an advanced user, allowing me to closely monitor and understand the inner workings of key Polkadot-JS repositories, such as polkadot-js/api, polkadot-js/apps, and polkadot-js/common.
Goals & Overview
Polkadot-JS plays a critical role in the ecosystem. Despite the promising Polkadot-API development, maintaining and developing Polkadot-JS remains essential for the ecosystem’s overall health.
In summary, my contributions to this project aims to achieve the following goals:
- Increase outside contributions.
- Restart regular maintenance with documented processes.
- Restart regular releases.
- Try to ensure a short turnover with issues, bugs, and PRs.
- Update libraries with necessary upstream changes.
- Ensure there is no single point of failure.
Let’s take a deeper look at how I plan to do this…
Priorities
Releases & Documentation
The aim here is to reinstate a regular release cadence for key Polkadot-JS libraries, and document the process in order to help eliminate any single point of failure, providing detailed instructions on releasing libraries and managing the dependency tree.
Documentation and releases will be considered top priority, and will be aimed to be finished within the first month.
The release process can be summarised as:
- Wasm and Common: Mondays when necessary
- Api: Bi-weekly on Tuesdays
- Phishing, UI, Extension, and Tools: Wednesdays when necessary
- Apps: Bi-weekly on Wednesdays or Thursdays
To understand this in more detail, the following dependency tree demonstrates the inheritance of Polkadot-JS libraries that would need to be released in order, where libraries each depend on the ones above them in the list.
As a note, @polkadot/dev is a dev dependency used in all the repos and does not affect production releases, but that being said the library contains all the necessary scripts and configs that the rest of the packages rely on.
@polkadot/dev - A collection of shared CI scripts and development environment (configuration, dependencies) used by all @polkadot projects.
|
@polkadot/wasm - Various WASM wrappers around Rust crates (Primarily used in @polkadot/common)
|
@polkadot/common - Various useful utility functions that are used across all projects in the @polkadot namespace.
|
@polkadot/api - Provides a clean wrapper around all the methods exposed by a Polkadot/Substrate network client and defines all the types exposed by a node.
|
@polkadot/phishing - A curated list of potentially less-than-honest sites inclusive of a simple JS utility function to check any host against this list.
|
@polkadot/ui - Basic browser and framework agnostic UI components for creating apps using the polkadot{.js} libraries
|
@polkadot/tools - This is a collection of cli tools to use on Polkadot and Substrate chains.
|
@polkadot/apps - A Portal into the Polkadot and Substrate networks. Provides a view and interaction layer from a browser.
Given this dependency tree, the following schedule will be similar to the releases many were used to for the Polkadot-JS libraries in the past, but instead of being weekly it will be bi-weekly with the exception of urgent patches, as well as shifted to during the week instead of the weekend. More specifically, releases will follow this schedule every 2 weeks:
- Wasm and Common: This will generally be released on Mondays. These libraries do not change often, and so this step can often be skipped.
- Api: The api will generally be released on Tuesdays on a bi-weekly basis. This is to ensure there is plenty of time for updates and the ability to file issues if any bugs are present. Urgent patches will be addressed on an ad-hoc basis when necessary.
- Phishing, UI, Extension, and Tools: This will generally happen on a Wednesday when necessary. These tools don’t often have releases but when necessary will be released before the Apps repo.
- Apps: This will generally be released on Wednesday, or Thursday depending on the above releases.
I’ll be working to document the release process for each library, ensuring a smooth and consistent schedule.
Issues & Bugs
Addressing outstanding issues and bugs is a priority. The focus will be on repositories such as @polkadot/api, @polkadot/apps, @polkadot/common, and @polkadot/extension. Prioritisation will be based on issue completeness and the presence of a reproducible example, as well as the overall urgency of the issue.
This doesn’t mean the other repositories won’t gain attention, but just that the above will be priority (unless there are needs for an urgent patch).
Currently there is a backlog of issues that need to be addressed. This can be specifically seen in @polkadot/apps, and @polkadot/api. Issues will be prioritised by the following:
- Does the issue answer all template prompts?
- Is there a reproducible example for faster resolution?
Setting a high bar for issue quality will hopefully ensure that issues and bugs can be resolved in a timely manner, and will also help to lower the barrier for entry for contributors. This will require a bit more organisation. Previously the maintainer of Polkadot-JS did an amazing job with response time to issues and dealing with bugs and upstream changes. I would like to restore that habit.
For issues that contain feature requests, the Features & PR’s section below will cover that.
Features & PR’s
Prioritising features will follow an upstream and contributor basis. Initially, the emphasis is on maintaining releases, documentation, and resolving issues and bugs. Large PR’s introducing features will need to be discussed with maintainers or the community to ensure viability and agreement. This is important to help prioritise PRs which have a good ratio of maintenance cost to overall value.
It is important that we do not introduce any breaking changes to the api and or any dependencies upstream. I would consider a large portion of the architecture to be in a stable condition with plenty of legacy commits to use as reference for any ongoing future work. Therefore a majority of the PR’s and ongoing work will be around maintenance and ensuring stability. I would expect any big PR’s that include features from outside contributors to be discussed in issues first with maintainers or the community to see if there is viability and merit. This will ensure that no time is wasted, and everyone can agree on an optimal solution.
To summarise:
- The emphasis is on maintenance and stability.
- We will expect discussion of significant PR’s in issues before implementation.
Given the limited bandwidth during the early stages, it is crucial to prioritise filing quality issues for features to encourage active community engagement.
Delegation & Organization
Avoiding a single point of failure is crucial. Delegating tasks to team members and other community contributors will happen when expertise is needed, bandwidth requires allocation elsewhere, or when I’m unavailable. Tasks and progress will be transparently managed on a public project board.
The public project board will be maintained and kept up to date with:
- Todo Tasks
- In Progress Tasks
- In Review Tasks
- Completed Tasks
This should also allow outside contributors to see available work that can have immediate impact and is waiting to be assigned.
Conclusion
In conclusion, the commitment to the continued development and fortification of Polkadot-JS is a shared endeavour that involves not only the dedication of an individual but also the collaborative efforts of the community. As we move forward, the outlined goals and priorities underscore a strategic approach to ensuring the health and adaptability of this critical component within the Polkadot ecosystem.
Special Thanks
A special acknowledgment is due to Jaco, the lead maintainer, and creator of Polkadot-JS. His invaluable contributions have not only facilitated seamless interaction with the Polkadot network but have also resulted in the development of an extensive toolkit that simplifies some of the most challenging aspects of Substrate. We express our sincere gratitude to Jaco for making participation in this ecosystem an enjoyable and enriching experience.
I extend special appreciation to Iker, my manager, and James for their assistance in reviewing and assembling this post.
