A practical guide to Semantic Versioning in Go

mintc2 — Tue, 12 Aug 2025 00:00:00 GMT

Why does this article exist?

One would think that semantic versioning is a simple enough concept that there would be nothing to talk about. "Major, minor, patch," and we're done.

But over the years of working with Go professionally and having the privilege of maintaining a couple of libraries, I've seen so many peculiar things, knowledge gaps, and misuses that by now I'm convinced that this topic has some depth to it and that it’s worth explaining in detail.

What is Semantic Versioning?

I will use a slightly modified definition from the Go docs.

"It's a versioning scheme where a module’s developer uses each part of a module’s version number to signal the version’s stability and backward compatibility. For each new release, a module’s release version number specifically reflects the nature of the module’s changes since the preceding release."

Stage	Version example	What bumping the stage means
Major	v1.X.X	Signals backward-incompatible public API changes. The "public API" is not only code declarations but also expectations for how the library behaves. This release carries no guarantee that it will be backward compatible with preceding major versions.
Minor	vX.1.X	Signals backward-compatible public API changes. This release guarantees backward compatibility and stability.
Patch	vX.X.1	Signals changes that don't affect the module's public API or its dependencies. This release guarantees backward compatibility and stability.
Pre-release	vX.X.X-rc.1	Signals that this is a pre-release milestone, such as an alpha, beta, or release candidate. This release carries no stability guarantees.

How to decide which stage to bump

First, you just have to ask yourself a question, "If the clients were to pull this new version I'm about to publish, would they need to modify anything in the code or adjust their assumptions about how the library functions to be able to continue using it?" If the answer is "yes, they need to adjust," that's a breaking change that warrants a new major version.

Otherwise, it's a standoff between "minor" and "patch" versions. If you've added something new, it's a minor version bump. If you didn't add anything new, it's a patch version bump. In rare cases where you can't decide between those two, just bump the minor version.

Special meaning behind v0.X.X

The major v0.X.X carries the special meaning of "this is a development version; backward compatibility is not guaranteed." What that means in practice is that it throws the whole semantic versioning out the window and you can even expect to get a breaking change between v0.0.0 and v0.0.1.

You probably shouldn't publish the library as v0 unless you specifically want to experiment with the API before you settle on something you can guarantee backward compatibility on going forward.

Major Version Suffix Rule (MVSR) and v2.X.X

Now let's take a look at the semantic lord of confusion, the dreaded major version 2. If you simply try to publish the tag v2.0.0 and then fetch it, you will get this infamous error.

go: github.com/mintc2/lib@v2.0.0: invalid version: go.mod has post-v2 module path "github.com/mintc2/lib/v2" at revision v2.0.0

That's because any module with major version v2.X.X or more has to append the suffix /v{major_version} to the module name in the go.mod file and when importing it.

It's confusing and rightfully so:

This rule has many names and none of them are short.
It only affects major versions v2.X.X and above (for example, v3.X.X and v4.X.X).
It has a "magical string" vibe to it.
Most importantly, it messes with a mental model many developers have that "module name = Git repository path."

To make understanding easier, you can use this mental model instead. Imagine that v0.X.X and v1.X.X also have suffixes, but those suffixes are phantom ones. They are the OGs; they were there early, so they have the special privilege of being invisible, while all versions that come afterward do not get such special treatment.

The many benefits of MVSR

As confusing as it is, the MVSR has a formidable list of things that make it good.

The first benefit is that the process of appending a suffix to the import path when fetching a new version and importing it into code makes accidental major version upgrades all but impossible. It has to be a conscious decision on the part of the library consumer.

The second thing is that you can have as many different major versions imported at the same time. At first glance, it doesn't seem like it would have any practical use, but it does. For example, if you have a Kafka wrapper library that defines publishers and consumers, you may decide that you only need to upgrade to the v4.X.X consumer while keeping the publisher on v3.X.X. This kind of flexibility is very valuable when you have deadlines to meet.

And the third thing is that the development of different major versions may continue in parallel, which, in combination with the point above, grants the developers even more flexibility.

The zero-major dodge

Not everyone likes the MVSR. Some dislike it so much they resort to an unofficial trick—I’ll call it the “zero-major dodge.”

It works like this: the versioning scheme vMAJOR.MINOR.PATCH is shifted to v0.MAJOR.PATCH, sidestepping the need to append a /vN suffix to the module path.

And it’s a bad idea: it violates Go’s conventions, misleads users about stability, and can silently break consumers who don’t get the clear migration signal a proper /vN path provides.

So don’t use this trick, it isn’t worth it.

Conclusion

I hope this article has convinced you that following semantic versioning is a pretty good idea and given you the knowledge to do so.

Tactically denying the internet access to the built-in MacOS services

mintc2 — Sun, 07 Sep 2025 00:00:00 GMT

The Background

One day I woke up and decided it was time to turn LittleSnitch loose on the built-in Apple services. If a service isn't required for the system to work properly, then at best it's a waste of bandwidth. At worst, well, that's anyone's guess.

But I didn't just want to block everything. I still wanted updates, the ability to verify signatures, and to keep my clock synced. Blocking anything related to the Apple ecosystem, though, felt like fair game to me.

So I sat down and started browsing, looking to see if anyone had already done the research on what various macOS services do and compiled a blocklist. Alas, the only worthwhile thing I found was this article on IntelTechniques from 2021. The author went nuclear, blocking almost everything. That would definitely break things I wanted to keep working.

That left me in a tough spot. Either I'd have to experiment heavily to figure out which services were safe to block, which would take a long, long time. Or I'd need to scour the internet for scraps of information on dozens of services, which wouldn't be swift either.

Then it hit me: AI could do the research for me and estimate the consequences of blocking each service. Even though the list wouldn't be perfect, it would let me cull the majority of useless services while giving me a solid starting point to test the rest.

The Crawler

I extracted the paths and descriptions (where available) of the built-in services LittleSnitch recognized and made a nicely formatted file out of that. I decided to use TOML, since it's a structured, well-known format. I figured the AI would be more attentive to it, potentially have built-in tools to work with it, and be less likely to drop entries. TOML was also the most readable option I could think of, so I went with it.

Then I gave that file to GPT-5, crafted a precise prompt describing what I wanted, and sent it crawling away in deep search mode. About 40 minutes later, it came back with the completed list. I had told it to fill in missing service descriptions, figure out any potential consequences of blocking internet access, and give a certainty score for each conclusion.

You can find this file here.

Time To Block

After reading the analysis and experimenting, I settled on the following whitelist.

Service	Why
mDNSResponder	Blocking it may lead to DNS resolution issues.
syspolicyd	Blocking it could disrupt Gatekeeper’s ability to verify apps, potentially preventing some applications or plugins from launching.
swtransparencyd	Blocking it disrupts Gatekeeper/notarization checks; launching apps may be slow or fail if their security cannot be verified online.
idleassetsd	Contains some buggy code; blocking it may trigger an infinite retry loop that burns CPU.
networkserviceproxy	A proxy used by other Apple services. Blocking it could cause cascading problems that are hard to diagnose. I didn’t really want to deal with that, so I left it allowed.
mobileassetd	Responsible for downloading fonts, dictionaries, and other system assets.
softwareupdated	Part of the system update mechanism. I want to continue getting updates.
nbagent	Also part of the system update mechanism.
NRDUpdated	Also part of the system update mechanism.
UpdateBrainService	Also part of the system update mechanism.
nsurlsessiond	Any application can delegate data transfers to this daemon. Since I’m not sure which apps rely on it, I left it in the allow list.
geod	The map inside LittleSnitch stopped working when I blocked this service, so I allow it now.
trustd	Responsible for certificate checks—pretty important security stuff.
timed	Keeps the clock synced.

All in all, I blocked 43 out of 57 built-in services (~76%). My system continues to function well, and I recently received the macOS Sequoia 15.6.1 update without issues.

Conclusion

Once again, you can find the analysis here.

If you're interested in blocking some of the built-in services but have different needs, maybe you're more extreme about privacy, or inversely need parts of the Apple ecosystem to work, you can use the report as a starting point to build an allow list that fits your needs.

Minty Blog

A practical guide to Semantic Versioning in Go

Why does this article exist?

What is Semantic Versioning?

How to decide which stage to bump

Special meaning behind v0.X.X

Major Version Suffix Rule (MVSR) and v2.X.X

The many benefits of MVSR

The zero-major dodge

Conclusion

Tactically denying the internet access to the built-in MacOS services

The Background

The Crawler

Time To Block

Conclusion