semver VS changesets

It seems to me that a lot of people are forgetting that when updating to next major version of a package, breaking changes are expected - that's the whole point of major version number in SemVer [1]. What they actually want is seamless updates (or never changing APIs, but that not possible in most situations, and also not what you want as a package developer - you want to be able to correct your API design mistakes). That requires a lot of work from the package developers.

Look for example how people at Remix do it: breaking changes are hidden behind future flags [2], so you a user can turn them on one by one and adapt their code on gradually without surprises. Another solution is creating codemods for upgrades. But how many open-source package developers are willing do to this extra work?

Same story with peer dependencies - they're completely fine, if package developers know how to use them.

As always, don't be mad at React, don't curse Npm, it's not their fault. There is no great package without great effort.

[1] https://semver.org/

You can always check the official Semantic Versioning Specification.

Using Semantic Versioning for version control.

Suppose our pre-pre-production environment is named STAGING, and our pre-production environment is named UAT. STAGING corresponds to the latest commit in the main branch - that's the 'bleeding edge'. UAT corresponds to the latest release candidate tag on the main branch. In semantic versioning, this would be achieved by adding the suffix -rc.N to the name of the release it's targeting. For example, if our goal is to create production release v12.0.0, our UAT environment commits would be tagged v12.0.0-rc.1, then v12.0.0-rc.2, and so on. Suppose on v12.0.0-rc.5 we finally feel confident enough to push to production. We would then add the tag v12.0.0 to the same commit, which would constitute a full release and then be automatically deployed to production.

SemVer.org

If you don't know what semantic versioning is, I suggest you read up on it. In a nutshell, it is a standard/guideline for defining version numbers and how to increase them:

We know that our packages need to have a version. This version follows a format called semantic versioning. This is where the job called generate-version comes in. The output of this job is a version number that will be used when we publish our package in the package-and-publish-lib job.

I frequently need to set a semantic versioning version number when building ASP.NET Core API projects, then read or report this at runtime.

When you are trying to understand the source code, you can use documentation as your starting point and search for variables and functions to set the direction for your exploration when you are dealing with large projects like Changesets.

In this article, an overview of Changesets and its usage in t3-env are provided.

As a general rule, I recommend against completely automating the release of your software and instead have a manual approval step required at some point in the process. Tools like changesets, the one we use at Latitude, greatly help with this. Changesets takes care of publishing new packages, updating changelogs, and tagging releases, yet it can only do so via automatic pull requests that have the same approval requirements as any other PR at Latitude.

All these versioning management is done with Changesets library

In my circles, this is the go-to for release automation / changelogs: https://github.com/changesets/changesets

🦋 Publicando com changesets

Open source libraries and frameworks share a common necessity: the need to develop multiple packages cohesively and efficiently while managing their versioning and publishing to NPM. Nx has emerged as a go-to choice for handling such open source monorepos (as we'll explore further in the next section of this blog post). Until recently, one area Nx did not address directly was versioning and release management. Traditionally, this gap has been filled with tools like release-it, changesets, or custom Node scripts, similar to our approach in the Nx repository.

Doing these tasks by hand can quickly become a hassle. If you're open to receiving contributions from others, it can be an even bigger headache. In this post we'll cover how to use changesets to automate all of these steps.