SemVer MAJOR release policy

[ephys]

Hi all :)

I'm opening this to talk about what we want our SemVer MAJOR release policy to be.
Right now, for v7, we've opted for the approach of "implement as many breaking changes then release v7"

I'd like to discuss an alternative policy: Releasing SemVer MAJOR releases on a fixed schedule.

The main reason behind it is that a lot of our dependencies already release their Major versions following a fixed schedule ; and, more importantly, EOL their old versions at fixed dates.

If we wait until we have enough breaking changes for v7 to release, we'll be stuck supporting versions of Node, Postgres, etc that have been EOL for a long time (because of v6).

What I'd like to do instead is this:

• Every year in May-June, we release a new SemVer MAJOR version of Sequelize. I've picked these months because Node typically EOL in April.
• New SemVer MAJOR releases only support TypeScript versions that were released in the past 365 days (we don't drop TypeScript versions between SemVer MAJOR releases).
• New SemVer MAJOR releases only support maintained versions of connectors, databases, and Node (at time of release).
• We drop support for a Sequelize version 6 months after its replacement was released. As such, each version would be maintained for a year and a half total.

This also make it easy to be explicit about which version supports which dependency:

Imagine we're in mid-june 2022, our version table would look a bit like this (with most dialects omitted):

Sequelize	Node	TypeScript	Postgres	pg (npm)	Released	EOL
8 (alpha)	>=16	>=4.7	>=11	>=8	2023-06-01	2025-01-01
7 (current)	>=14	>=4.4	>=10	>= 8	2022-06-01	2024-01-01
6 (maintenance)	>=10 <=18	>=4.1	>=10 <=14	>= 7 (node 10-12), >= 8 (node 14)	2020-06-24	2023-01-01
5 (EOL)	>=6 <=12			7	2019-03-13	2022-01-01

Table built based on:

• https://github.com/microsoft/TypeScript/wiki/Roadmap
• https://nodejs.org/en/about/releases/
• https://www.postgresql.org/support/versioning/

[WikiRik]

I think this in general is a good idea, but in my mind we already have two new major versions planned;
v7 with the TypeScript migration and other breaking changes
v8 with the dialect splitting and maybe the query builder? (if that doesn't fit in with v7)
So I would say that we postpone this until we have released v8 and then look into this further. Maybe we can also look into using different version numbers for the dialects we've split so that they can do their own policy for dropping support for database/connector versions if the demand is there.

[ephys]

The thing is that the TypeScript migration is going to take a long time to complete, we've been at it for a few months and only 4.3% of the codebase has been migrated.
Splitting dialects is also going to take a very long time

We may have to wait a long time before we're able to release v7 (work on v8 hasn't even started yet) if we have to wait for these changes to be fully implemented, which means that:

• We'll have to continue to maintain support for node 10 for a while (as we won't drop support for v6 the moment v7 is released) even though it's been EOL for a year now
• We'll either stuck supporting old TypeScript versions, or have to drop them in SemVer MINOR versions for v6
• Users won't have access to the new v7 features for a long time
• Users will have to deal with many breaking changes in the same upgrade, which is discouraging

Nothing is stopping us from releasing what's currently stable in v7 in june, move v6 to 'maintenance' (bugfixes only) and continue implementing new features in v7, and keep new breaking changes for v8.

(even the TypeScript migration can be continued in v7, if we block access to /lib before the stable release)

---

I also don't think it's a good idea to release affiliated packages with a different MAJOR number than core. It's standard nowadays to make them follow the same version number, which helps indicate that they're compatible with each-other. It's what lerna does by default if we end-up using that, and we can see this convention in babel, nest, and other large multi-package projects.

[sdepold]

Q: Should we still release a final v7 under "sequelize" npm module or go with "@sequelize/core" onwards now.

Edit: My thought is that we should probably stick to our previous idea of deprecating the v6 version with a hint that people should migrate to "@sequelize/core" and stop releasing v7 version under "sequelize" because otherwise people will expect that new updates will be released there in the future as well.

[WikiRik]

Maybe we should deprecate the v7 alphas under 'sequelize' already? So they will move to '@sequelize/core' for the next alphas

[WikiRik]

But to get back to the original point. I agree that the TypeScript migration and splitting dialects will take a long time so it might be better to work on a fixed release schedule earlier than for v9.
Only thing I worry about is that we are generating quite some breaking changes in the TypeScript migration because we see weird stuff and solve it directly. If we would continue the migration in SemVer MINOR versions we would not be able to do that. But seeing as there is still quite some work to be done on that, I can go both ways. So either waiting with v7 until we have migrated and start on a fixed schedule afterwards in v8 or start doing this in May-June for v7 already.

@sdepold @allawesome497 do you have any thoughts on this?

[ephys]

If we would continue the migration in SemVer MINOR versions we would not be able to do that

That's a good point. We'd have to either write down the thing we want to change and implement it in the branch of the next major, or migrate these files in the next major

The current state of things where the codebase is mostly TS in v7, and mostly JS in v6 makes backporting things annoying. It may be wise to wait until src is migrated to TS to avoid this situation for v7-v8.

But at the same time, what remains to be complicated is massive and complicated (dialects & model) and I don't know how long it's going to take to finish migrating them.

We can always assess the situation in June, see whether we're far enough into the migration to release

[mike-usa]

Release Schedule

Every year in May-June, we release a new SemVer MAJOR version of Sequelize. I've picked these months because Node typically EOL in April.

I like this thought. It gives some structure to the release schedule.

Questions

1. When are the major dialect's versions considered for Sequelize coverage?
   1. Will Sequelize automatically support every major version of a dialect at the time of its major release date?
   2. Does it matter if Sequelize can't support a major version at that time?
2. If Sequelize does not require any new coding around a Node.js upgrade (or dialects' upgrades), does Sequelize bump its major version? (see Hypothetical below)

Comments

• Is this to tether Sequelize versioning to Node upgrades? That may make the most sense if tethering it to something, since Node is the non-db component of the tech stack, but it also means Sequelize versioning will be tethered to something that may have no impact on Sequelize's features or capability
• I think it's a good idea to keep the schedule, but still plan out all the new breaking features that are expected to be included in that major version and if they can't be hit, don't make it a LTS version (e.g., Node/Ubuntu odd-number major versions)

Hypothetical

• Node v20 -> v22 does not require Sequelize to modify any of its code. Likewise, all dialects that Sequelize supports, including any new major version, are still supported by the same codebase. Sequelize code remains unaltered.
  1. Should this require a Sequelize version change?

Major Version

v7 with the TypeScript migration and other breaking changes
v8 with the dialect splitting and maybe the query builder? (if that doesn't fit in with v7)

Will the TypeScript or Dialect-splitting require changes to the User's code? If they include substantial refactoring, but are backwards compatible and no breaking changes, I think SemVer encourages those to be patch updates; no change in feature, no bugfix, but could introduce a new bug.

[ephys]

When are the major dialect's versions considered for Sequelize coverage?

Sequelize supports all dialect versions that are not EOL at the time of release, and all dialects versions released afterwards as long as that version of Sequelize itself is not EOL

Does it matter if Sequelize can't support a major version at that time?

No because we can always add support in a minor/patch version of Sequelize.
We can't remove support for databases in a minor/patch release though.

If Sequelize does not require any new coding around a Node.js upgrade (or dialects' upgrades), does Sequelize bump its major version?

Yes but not for the reason I think you're thinking of: We don't release a major to support a new version of Node, but to drop support for EOL versions of Node.

e.g. Sequelize 7 supports Node >= 14. Sequelize 8 will likely support Node >= 16. Both will continue to support new major releases of Node until we stop updating them (until they've reached EOL as well).

Not doing that forces us to continue supporting dead versions of node (or databases). For instance, Sequelize 6 still has to support Node 10 (dead for 2 years), and postgres 9.5 (dead for one year)

Will the TypeScript or Dialect-splitting require changes to the User's code?

Very likely to be the case for TypeScript, as we also refactor the APIs.
100% going to be the case for dialect splitting.

[sdepold]

We are not really close to what we wanted to complete in https://github.com/orgs/sequelize/projects/1/views/1. Hence we could either release a v7 now and finish the ts migration in v8 or keep everything as in and release v7 only when TS migration is completed.

Zoe: Let's remove everything from that backlog that is not TS related.

When should the new release happen? --> We will release once TS migration is done and deprecate V6 after release + stop maintaining 6 months later.