[Docs] Guide and recommendation on pinning CLI version

[bombillazo]

Link

https://supabase.com/docs/guides/cli

Describe the problem

The reality is that, as specified in this repo description, the Supabase CLI is a WIP and iterating constantly/quickly, therefore unstable.

However, this is not reflected in the official docs, and the expectations of a reliable CLI do not align with the reality of the CLI's state. We've had multiple occurrences of a broken dev process due to a new CLI update.

Describe the improvement

I would highly recommend adding a guide on how to pin the CLI version in a project to avoid frustrating developers with unexpected issues.

[bombillazo]

A PR was created. supabase/supabase#14624

[sweatybridge]

Thanks for the suggestion. The getting started guide is mostly for on-boarding users who are new to cli. This usually means they want to install the latest version. Hence, I would avoid mentioning any specific version in the guide.

Instead, I would propose to follow a fixed release schedule, perhaps once every two weeks. The detailed plan is as follows:

1. Create a beta release channel on npm. Builds from main branch will be released to beta channel as soon as they are merged. Brew, scoop, and other package managers will not be updated by merge to main.
2. Once every 2 weeks, we will create a new release tag on main branch to update brew, scoop, and other package managers. The tag does not need to use the latest beta version as we can manually pick the stable commit to release. This means we have more time to test changes before releasing to everyone.
3. When we need to release a hotfix, we will branch off from the last stable tag and cherry-pick commits from main branch. This hotfix branch can be deleted after the next regular release.

In addition to better stability, there are several other benefits to following a fixed schedule.

1. New features can be released to a small group of beta testers without requiring them to compile from source or jeopardise stable release.
2. Users who rely on setup-cli action for CI can specify version: latest with greater confidence as it will install from the stable channel.
3. Anyone can opt in to the beta channel on npm if they prefer using the bleeding edge for local dev.

[bombillazo]

That would be even better! I was suggesting a quick solution, but if that can be done, then I support the proposal.

I'm not sure how quickly you can "officialize" this approach, but in the meantime, it would be helpful to let newcomers know to beware of/how to pin to their current version. I agree we can remove the specific version from the example to avoid confusion.

[sweatybridge]

We have added beta release tag to npm as discussed. You can try it out with npm i --save-dev supabase@beta or continue using the latest release tag which is stable.

The command npm i --save-dev supabase already pins the version of CLI by updating dev dependencies in package.json. I believe this is sufficient for most new users to get started.

Once package.json and package-lock.json are committed to git, others can install the pinned version by running npm ci.

[bombillazo]

Sounds great! What is the planned cadence for updates to the stable version?

[sweatybridge]

Currently the planned cadence is 2 weeks for stable version. I will document more in the contributing guide #1163