Advisory: Specify 1.x version explicitly for legacy content

[steveluscher]

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