Advisory: Specify 1.x version explicitly for legacy content #3498
Description
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