Bun releases: Use semantic versioning, or something close to it

[dylang]

If we assume <major>.<minor>.<patch> is <breaking changes>.<new features>.<bug fixes>...

Major

At this point every release could be a breaking change for somebody, but maybe we reserve major bumping for when we know a significant number of developers will need to change their code if they want it to continue working.

Examples:

• Required changes to bunfig.toml.
• Backwards incompatible changes to Bun.* apis.
• New bun.lockb format that older versions of bun can't use.

Minor

1.0.1 and 1.0.2 both introduced new features, so they should technically be 1.1.0 and 1.2.0. This hopefully signals to developers: "It's not just bug fixes, you probably want to look at the release notes to see what's new!"

Patch

For bug fixes. Nothing should break.

Reasoning

As a project maintainer, I want some consistency between developer machines and CI. I want to be able to say "we're compatible with Bun 1.x" - and then when Bun releases a breaking change, I hope to get a PR for supporting Bun 2.x, not bug reports that my project is broken.

References

I remember these being helpful when I was learning about semver:

• https://semver.org/
• http://sentimentalversioning.org/

[melroy89]

Fully agreed.

[tomerh2001]

I suggest to use semantic-release

[melroy89]

Which is following the https://semver.org/ spec...

[tomerh2001]

Yeah that's why I suggested it :)

[yamcodes]

100% agree. Our code that was working before now isn't working because we've updated what we thought was a minor version, only to be surprised it included breaking changes.

E.g. this happened multiple times in this Issue: dotansimha/graphql-yoga#3003
Type changes in the Bun.serve() function broke the usage twice over a year.

We need a semblance of SemVer here, to make working with Bun more straightforward.

[melroy89]

That sounds painful indeed. Sorry you went through this.

[Jarred-Sumner]

Our code that was working before now isn't working because we've updated what we thought was a minor version, only to be surprised it included breaking changes.

Type changes in the Bun.serve() function broke the usage twice over a year.

Sorry about this. Were the breaking changes to the TypeScript types or to the usage? Was this a breaking change when running the code or when checking the types?

[yamcodes]

Thanks @Jarred-Sumner and @melroy89!

Unfortunately, I'm unable to recreate the previously working code now with the bun-types and graphql-yoga versions that worked before (1.0.2 and 4.0.4, respectively). I'm not sure why. For safekeeping, here is the documentation for when things broke: dotansimha/graphql-yoga#3003 (comment) (You can follow along the recreation example and see, but again I am unable to recreate it now to a state that is working as before)

Either way, the code is running just fine, the error is a tsc error so it was only happening when checking the types:

In any case, SemVer or not, we should set the bun-types version to something safer than latest when running bun init, otherwise code that was based on bun init and passed typecheck before can spontaneously break in compilation.

[hubdidub]

Strict SemVer has its upsides, but it isn't the all-round solution for everything.

I prefer dealing with the risk of breaking changes each update if that means the maintainers have the freedom to ship bigger changes without having to release new a "major" release like v458 because some parameter in a config was changed. Or, even worse, if that discourages them to improve things in the first place.

I think the current versioning scheme works for Bun, especially when it's growing and evolving as fast as it is currently.