which numbers to pick?

So you're an open-source maintainer (or even just a professional developer). You've just updated some code and you'd like to create a new release.

You've built and tested everything, and now the only question left is to bump the version. But what version should you bump to?

You are on version 2.3.4 and you fixed a bug.

2.3.5

the final digit is a patch version, and incrementing it means a bug fix with no breaking changes.

You are on version 8.1.1 and you released a bunch of breaking API changes.

9.0.0

When you break functionality across versions, you should let the users (and their automation) know. It's best practice to reset the MINOR/PATCH versions to 0 when bumping a major version.

You are on version 1.0.25 and you release some new features, but everything's backwards compatible.

1.1.0

Like updating the MAJOR version, when you upgrade the MINOR version, be sure to reset the PATCH version to 0.

You are on version 22.0.8 and you release some new shiny features, but you ALSO change some of the existing functionality.

23.0.0

Whenever you release, if you changed anything in a non-backwards compatible way, you should let people know by bumping the MAJOR version.

You are on version 1.12.5 and you release a bugfix

1.12.6

the final digit is a patch version, and incrementing it means a bug fix with no breaking changes.

You are on version 0.10.6 and you release a whole bunch of new features and break a bunch of stuff.

0.11.0

One special case in semver is if things have a 0 for the MAJOR version, then they're intended as a development release with no promise of a stable API. Users can rely on features at their own discretion. In this case, we just bump the minor version even though things have changed.