Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal to stabilize Web3 1.x #3070

Closed
alcuadrado opened this issue Sep 16, 2019 · 10 comments
Closed

Proposal to stabilize Web3 1.x #3070

alcuadrado opened this issue Sep 16, 2019 · 10 comments
Labels
1.x 1.0 related issues Discussion Enhancement Includes improvements or optimizations

Comments

@alcuadrado
Copy link

alcuadrado commented Sep 16, 2019

At Nomic Labs we’ve been collaborating with the Ethereum Foundation to improve the developer experience on Ethereum, and we believe an important part of this process for the short-term is to help stabilize the web3.js library. In this document we propose a plan to move in this direction.

First, some quick context:

  • The 1.0.0-beta-38 release of the library broke backwards compatibility
  • Recently, the library was split into two branches
  • 1.x branch continuing from where the 1.0.0-beta-37 left off
  • 2.x branch, continuing from 1.0.0-beta-55. This branch isn’t backward compatible with 1.x.

The versions that are widely used across the ecosystem right now are the 1.0.0-beta-37 and its subsequent 1.x releases. These releases still contain a significant amount of known bugs that have been reported, are fixed on the 2.x branch, but remain live in the versions used in production depoyments due to the releases that now exist in the 2.x branch not having significant adoption.

The fixes done on 2.x represent a ton of work that’s already been done, and it would be great if it were repackaged in a form that is usable on the web3.js deployments across the ecosystem.

We’ve gone through all the releases between 1.0.0-beta-38 and 1.0.0-beta-55 (the latest release that became the 2.x branch) and collected the list of issues that have been fixed. Thankfully @nivida has done a great job at documenting each release.

Our simple proposal consists of backporting these bug fixes from the 2.x branch to the 1.x branch, where it makes sense. We assume there may be some issues in the list that shouldn’t be included or aren’t relevant anymore.

The main objective here is stabilizing the 1.x branch, so we believe stability should be the main driver for decision making throughout this process. From our perspective this would mean, at least:

  1. None of the backporting work should break backwards compatibility against the 1.0.0-beta-37 release
  2. If an issue in this list isn’t a bug it should be removed from the list
  3. If the bug reported in an issue in the list was introduced in a version later to beta-37, then the issue should be removed from the list
  4. Release management should be thoroughly considered

If an issue is removed from the list because of 2 or 3, it would be valuable to keep track of this.

When it comes to releases we think there should be an RC release, which teams relying on the library can test comfortably, and once any issues that arise are fixed then the proper release.

Prioritizing this list represents a difficult task to us, so we invite people with a more intimate knowledge of the codebase to highlight issues of major importance that should be included in the first release. The list is ordered in the exact same order the fixes were released on the 2.x branch, so we assume there’s been prioritization done by Samuel already. Overall, given that projects relying on the library have been a long time without a release that’s compatible with their deployments, and the work doesn’t need to be done from scratch, we think that just aiming to follow that same release order and getting them all released as soon as possible on 1.x is a reasonable approach.

When it comes to the cadence of the releases containing these fixes, we wouldn’t prioritize speed. We think that appropriately spaced releases that allow the community to properly test each release candidate is important. The objective of such a stage in each release is to identify any new issues that might have been inadvertently introduced, and fix them before moving on to the final release. Given that the amount of issues is significant (244 in the unfiltered list we collected), there should be enough time in-between each release for proper testing. We believe this is somewhere between 3 and 6 weeks between each release.

In addition, given that the 1.x branch is considered the stable release and the 2.x branch is considered the development branch, we suggest the default branch on the Github repository be set to 1.x. The rationale being to help the userbase easily access the code they’re using as a reference when needed.

We welcome any ideas and suggestions that would add to this proposal for a short-term plan to bring more stability to web3.js.

If you agree this should be the way forward, please voice your support below in the comments or with a thumbs up reaction.

⚠️ Tracking issue: active editing in progress... ⚠️

These are the items on @alcuadrado's / NomicLab's original list, organized into 4 categories:

  • Needs investigation
  • Triage (e.g we've identified that these need back-porting, regression tests, or both)
  • Removals with a documented reason (e.g. is fixed, wont-fix, duplicate, etc)
  • Removals based an initial pruning of the list by @nivida, waiting for a documented reason.
    • Many of these may only be relevant to the 2.x branch

(Goal is to move everything into the Removals with Reason category.)

@joshstevens19 has added an additional set of PRs relating to stabilizing Typescript on 1.x in a second comment below.

There's a copy of the original list here

Editors: (if you're editing, pls add your name here)

Needs investigation

Bundling / Publication

Dependencies

Security

Other
(Added back in because of recent reports that it's alive...) (cg)

Broken

Typescript

@joshstevens19 will solve all of these.

These can probably all be addressed by a single back-port PR from 2.x, after modifying
the latest types as necessary and double-checking everything makes sense.

Lower priority

PR Opened (back-porting...)

Removals (with reason)

Duplicates

Wont fix

Is fixed in 1.2.1

Only relevant to 2.0 Branch

I've commented out the list here because the listed issues arent relevant to stabilize 1.0. (nv)
I've uncommented out this list so we can see the complete survey (cg)

@joshstevens19
Copy link
Contributor

Hey nice, I can't see many of the PRs for the new typings which we spent a lot of time on and it works perfectly in TS projects now. This matches the same interface as 1.0 as that did not change so we should get them in in my view:

#2844 #2645 #2618 #2550 #2516 #2471 #2422 #2417 #2416 #2415 #2336 #2322 #2288 #2280 #2278 #2262 #2261 #2253 #2231 #2219 #2218 #2217 #2203 #2134 #2133 #2128 #2125 #2123 #2122 #2121 #2119 #2118 #2114 #2113 #2112 #2096 #2090 #2084 #2078 #2073 #2056 #2753 #2672 #2643 #2619 #2585 #2575 #2557 #2556 #2529 #2479 #2478 #2355 #2233

@nivida nivida added 1.x 1.0 related issues Discussion Enhancement Includes improvements or optimizations labels Sep 16, 2019
@gnidan
Copy link
Contributor

gnidan commented Sep 17, 2019

I wrote a quick script to format the raw lists provided by @alcuadrado and @joshstevens19 into a list of checkboxes with issue titles:

(list moved to issue description)

I also started a GH project here to triage/organize the effort.

Hope these help!

@joshstevens19
Copy link
Contributor

joshstevens19 commented Sep 17, 2019

Happy to back-port every PR I put in my comment into 1.0 if you wanted a extra pair of hands. Let me know.

@cgewecke
Copy link
Collaborator

cgewecke commented Oct 4, 2019

@alcuadrado @nivida

I have gone though these in a first pass and sorted them a little. Have also opened a handful of PRs back-porting small fixes. My general impression is that many of the remaining things to fix are edge cases for which there are well-documented work-arounds in the issues or typescript related.

I've also marked a number of items as needing "E2E" - by which I mean: to safely fix these we should test vs a client, or validate against downstream project. #3098 contains some ideas about how to do that. . .

One way forward is to take a small detour and set CI up so that things can be addressed with greater certainty about what the consequence of a given change might be.

WDYT?

@nivida
Copy link
Contributor

nivida commented Oct 8, 2019

@cgewecke Let us discuss the e2e stuff in the related issue :)

@joshstevens19 I've added the types PRs above.

@frozeman
Copy link
Contributor

frozeman commented Nov 6, 2019

Nice to see that collaboration, makes my heart warm 💓

@pepihasenfuss
Copy link

I spent some time to find out that I have to go back to beta 37 to continue my work on my dapp.
Thank you for all the effort that is going into web3.js to stabilize the project.

Since I am not quite familiar with node.js, I would like to ask if the pre-built binaries web3.js and web3.min.js will be included in the zip in the future. It would very much simplify one's life.
It used to be the case some time ago.

@alcuadrado
Copy link
Author

I would like to ask if the pre-built binaries web3.js and web3.min.js will be included in the zip in the future

These are going to be (or already are?) included in the npm package. Is that what you mean? Or the zip file from the release section of Github?

@pepihasenfuss
Copy link

@nivida @alcuadrado @cgewecke
For me and perhaps many other developers, it would be highly appreciated if the web3.js binaries will be included in the git zip file release. It would be so much easier to test a new release immediately and it leaves out the build complexities with node.
I am not familiar with node, therefore I would prefer to test web3.js without the need of building it first.

@cgewecke
Copy link
Collaborator

Closing. This is mostly done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
1.x 1.0 related issues Discussion Enhancement Includes improvements or optimizations
Projects
None yet
Development

No branches or pull requests

7 participants