Advisory: Specify 1.x version explicitly for legacy content

[steveluscher]

trafficstars

Motivation

@solana/web3.js will advance to version 2.0 the first week of November. The API is a full break from the 1.x line, meaning that software designed for @solana/web3.js@1 will not work with @solana/web3.js@>=2. If you have content that installs @solana/web3.js without a version specifier, you can expect incompatibilities.

Example use case

NPM installs

A shell script that installs @solana/web3.js, or content that asks its readers to do this:

npm install @solana/web3.js

…will newly install version 2.0, which will presumably be incompatible with the rest of the software which is based on the 1.x line.

[!TIP] Update such install statements to include the version specifier: npm install @solana/web3.js@1

Code/app generators

If you maintain an app generator that causes an unbounded install of @solana/web3.js through a package manager, that install will newly install version 2.0, which will presumably be incompatible with the rest of the generated code.

[!TIP] Update such install statements to include the version specifier: npm install @solana/web3.js@1

Links to documentation

If you link to the @solana/web3.js TypeDoc from anywhere, please update those links to explicitly hit the version 1 docs.

Use this regex:

solana-labs.github.io\/solana-web3.js([^ \)]*)

…and replace the URLs with this:

solana-labs.github.io/solana-web3.js/v1.x$1

Details

Because of the way that JavaScript package managers work, installing a package without a version specifier will by default install whichever version carries the latest tag. When @solana/web3.js 2.0 is released, we will apply the latest tag to that version.

Read more about the 2.0 upgrade, here: https://www.anza.xyz/blog/solana-web3-js-2-release-candidate