Forem: Christian Holländer

Choosing the Right Versioning Scheme: It's About Who Consumes Your Software

Christian Holländer — Wed, 22 Apr 2026 10:38:39 +0000

This post was originally posted over on my personal website. Maybe you want to check it out [HERE].

Version numbers communicate to their consumer. Use SemVer when code depends on your interface externally. Use CalVer for human-facing software. The question isn't app type — it's: human or code consumer?

Every software project needs a version number. Yet the choice of how to version is often made by habit ("we've always used SemVer") or by imitation ("npm does it, so we will too") rather than by deliberate reasoning. This leads to version numbers that are either misleading, meaningless, or unnecessarily complex.

There is a cleaner mental model: your versioning scheme should match who consumes your software. Humans or code. That single question cuts through most of the confusion.

The Core Distinction: Human Consumers vs. Code Consumers

When a human uses your software, they interact with it through a UI. They click buttons, read screens, fill forms. They don't integrate against your software — they just use it.

When code consumes your software — a library, an API, an SDK — it integrates against a specific contract: function signatures, endpoints, data shapes, CLI flags. A breaking change has a precise, technical meaning: something that worked before now doesn't compile, fails at runtime, or returns unexpected data.

This distinction drives everything:

Code consumers need SemVer — because a version number is the primary communication channel about compatibility, and dependency resolvers literally parse it to make decisions.
Human consumers don't need SemVer — because what does a MAJOR bump even mean to a user? That you changed the navigation? Dropped a feature? Added a dark mode? None of SemVer's three signals map cleanly onto the human experience of software.

Semantic Versioning: A Protocol for Dependency Graphs

SemVer uses the format MAJOR.MINOR.PATCH:

MAJOR — breaking changes; dependents may need to update their code
MINOR — new features, backwards compatible
PATCH — bug fixes, backwards compatible

This scheme is elegant precisely because it was designed for a specific problem: how do you communicate compatibility to a dependency resolver that can't read your changelog? Tools like npm, Cargo, and Composer use SemVer ranges (^2.4.0, ~1.2) to automatically resolve compatible versions. The version number is machine-readable API documentation.

SemVer becomes truly necessary when two conditions are met simultaneously:

Your software has a programmatic interface (API, library, SDK, CLI used in scripts)
You have external consumers you don't control — third parties who can't update in lockstep with you

Open source libraries are the purest SemVer use case precisely because both conditions are maximally true: thousands of unknown downstream dependents, zero coordination possible. Your version number is the only signal you have.

Where SemVer fits:

Open source libraries and packages (npm, Composer, Cargo, PyPI)
Public REST APIs (the underlying package — not the v1/v2 surface, more on that below)
SDKs and client libraries
CLIs used in scripts and CI pipelines (where a renamed flag is a genuine breaking change)

Calendar Versioning: Honesty for Human Consumers

CalVer encodes the release date into the version number. Common formats include:

Format	Example	Used by
`YY.MM`	`25.04`	Ubuntu
`YYYY.MINOR.PATCH`	`2025.1.2`	JetBrains IDEs
`YYYY.MM.DD`	`2025.04.22`	Internal build artifacts
`YYYYMMDD`	`20250422`	CI/CD pipeline artifacts
`YY.MM.PATCH`	`25.04.1`	Twisted, pip

For user-facing software, CalVer is more honest than SemVer. The only thing that genuinely matters to a user is: is this newer than what I have, and roughly when was it made? A date answers that directly. 2025.1 tells you more than 4.7.2 ever could, without pretending there's meaningful semantic signal in those numbers.

Ubuntu's YY.MM scheme is a great example: 24.10 came out in October 2024, 25.04 in April 2025. No ambiguity, no inflated MAJOR versions, no "what changed to warrant a 2.0?"

Where CalVer fits:

Desktop applications with regular release cadences
Operating systems and distros
Any user-facing software where "when was this released?" is more useful than "what changed semantically?"

API Versioning: A Special Case

Public APIs have a unique challenge: they are programmatic interfaces (developer-facing), but the version isn't expressed as a package number managed by a resolver. It's expressed in the interface itself — typically in the URL path, a header, or a media type.

Common strategies:

Path versioning: /api/v1/users, /api/v2/users — explicit, widely understood
Header versioning: API-Version: 2 or Accept: application/vnd.myapi.v2+json
Query parameter: /api/users?version=2 — simple but pollutes URLs
Evergreen / no versioning: the API evolves without breaking changes, consumers always get the latest

The version number here (v1, v2) is just a sequential integer — what matters is the strategy for where and how you express it. In practice, most teams pair this with SemVer internally: the public API is v2, the underlying codebase is 2.4.1.

GraphQL is interesting here because its design philosophy pushes toward the evergreen approach. Schema evolution should be additive — deprecate fields rather than removing them, add types rather than breaking existing ones. Explicit v2 GraphQL APIs are generally considered a design smell, a sign that the schema wasn't designed for evolution.

The Internal Interface Exception

Having a programmatic interface doesn't automatically mean you need SemVer. A crucial condition is that you don't control the consumers — and this has nothing to do with how your code is organized.

Consider a Laravel application that serves both an Inertia.js frontend and a set of API routes. It's one codebase, one deployment, one composer.json. If those API routes are only consumed by your own frontend or your own mobile app, you own both sides of the interface. You can coordinate breaking changes through a pull request or a Slack message. SemVer's signaling function adds no value because the version number isn't anyone's communication channel — your team is.

The moment third-party developers start integrating against your /api routes, that changes entirely. Now you have external consumers you can't coordinate with, and your API surface needs versioning discipline — expressed via route prefixing (/api/v1/) or headers, regardless of how the underlying code is structured. The application version and the API version then become two separate concerns living in the same codebase, and only one of them needs SemVer.

The key insight is that repository or project boundaries are irrelevant. What matters is the consumer boundary: can you update all consumers when you make a breaking change, or not?

Consumer type	Scheme
Human users	CalVer, or marketing version
Programmatic, internal / same team	Optional — coordination suffices
Programmatic, external / public	SemVer or explicit API versioning required

What About Users Who Don't Update?

Mobile apps and browser extensions raise an interesting edge case: users sometimes sit on old versions for weeks or months. Does that make the app's version number developer-facing?

Not really — and the reason reveals something important about where versioning responsibility actually lives.

When an old client is still in the wild, the compatibility burden falls on your backend API, not on the app's version number. Your server has to keep supporting old clients — but that's an API versioning problem. The app version number itself still communicates nothing meaningful to the user in that scenario; they don't inspect 2.4.1 and decide whether to update, they just tap a button in the App Store.

The people who do care about the old app version are your team internally — for analytics ("how many users are still on the old client?"), support triage, and deciding when to sunset old API compatibility. That's a valid operational concern, but it's solved by internal tooling, not by adopting SemVer for the app itself.

The app version and the API version it consumes are two separate things that happen to ship together. Conflating them is a common source of unnecessary complexity.

Platform-Specific Constraints

Some platforms impose versioning formats regardless of your preferences:

iOS: requires a user-facing CFBundleShortVersionString and an internal CFBundleVersion. Both accept one to three period-separated integers — so 1.0, 25.04, and 2025.4.1 are all valid. CalVer like 2025.04 or SemVer like 1.4.2 are therefore both technically supported. CFBundleVersion must increase monotonically with every submission and is what the App Store actually tracks internally.
Android: the same dual pattern — a human-readable versionName which is a completely free-form string (any format works, including 2025.04 or 1.4.2), and an integer versionCode for the Play Store. Unlike iOS, versionCode is strictly a single positive integer — no dots, no components — and has a maximum value of 2,100,000,000.
Chrome Extensions: support 1 to 4 dot-separated integers (e.g. 1.0, 25.04, 1.2.3, or 2.0.0.1), each between 0 and 65535. The fourth component is optional — most extensions use three. Chrome uses this number to detect and trigger automatic updates.

In all three cases, users almost never look at the version — the platform handles update prompts. The version number is mostly an artifact for the store and for your own release tracking.

Quick Reference

Software type	Recommended scheme	Rationale
OSS library / package	SemVer	Dependency resolvers require it
Public REST API surface	v1/v2 path or header	Explicit consumer contract
GraphQL API	Evergreen	Additive schema evolution
SDK / client library	SemVer, major aligned to API	Mirrors the API contract
CLI (used in scripts/CI)	SemVer	Flag changes are breaking
CLI (interactive only)	CalVer or SemVer	Either works
Desktop app	CalVer	Date is meaningful to users
Mobile app	SemVer-like + build number	Platform-dictated hybrid
Browser extension	1–4 part integer version	Chrome supports up to 4 components, 3 is typical
OS / distro	CalVer + named releases	Ubuntu, Fedora model
SaaS / web app	None public / date+SHA internally	Continuous deployment
Internal services	Date+build or sequential	No external consumers
Firmware	SemVer or sequential	Clarity over semantics

Conclusion

The versioning scheme isn't a style choice — it's a communication tool. Before picking one, ask: who needs to understand this version number, and what do they need to know?

If it's a dependency resolver or an external developer integrating against your interface, give them SemVer. They need to know whether your update is safe to adopt automatically.

If it's a human user, give them a date or a name. They need to know whether this is newer than what they have.

And if it's an internal team coordinating a deployment, a Git SHA or a build timestamp is probably enough — you have other channels for communicating what changed.

The mistake isn't choosing the wrong scheme within a category. It's applying a scheme designed for one kind of consumer to an entirely different one.

MongoDB vs MySQL: A Real-World Performance Showdown Using Disneyland Data

Christian Holländer — Thu, 25 Sep 2025 11:40:40 +0000

This post was originally posted over on my personal website. Maybe you want to check it out [HERE].

MongoDB vs MySQL head-to-head: We benchmarked both databases with real Disneyland data. MongoDB won writes by 67% and some queries by 98%, but MySQL had surprises too!

When choosing a database for your next project, performance benchmarks often feel abstract and disconnected from real-world scenarios. That's why our recent university project comparing MongoDB and MySQL using actual Disneyland visitor data provides such valuable insights – we tested both databases against the same complex dataset with realistic use cases.

The Dataset: Perfect for Database Testing

We used a comprehensive Disneyland Paris dataset that presented real analytical challenges:

Wait times for 37 attractions (2018-2019)
Daily attendance data (2018-2022)
Weather conditions (1999-2022)
Park operational schedules (2018-2022)

This dataset was ideal for performance testing because it required:

High-frequency writes (weather data every hour, wait times every 15 minutes)
Complex aggregations across multiple data sources
Time-series analysis
JOIN operations between related data

Database Setup: Fair Fight Conditions

To ensure a fair comparison, we:

Identical hardware: Same server (20GB RAM, 6 CPU cores, HDD storage)
Equivalent indexing: Created the same indexes on both systems
Standardized schema: Normalized data structure for MySQL, embedded documents for MongoDB
Same queries: Translated identical business logic between SQL and MongoDB aggregation pipelines

Schema Differences

MySQL: Traditional normalized approach with separate tables for weather descriptions, linked via foreign keys.

MongoDB: Document-based approach with embedded weather objects, eliminating the need for joins.

Performance Results: The Numbers Don't Lie

We ran each query 100 times sequentially to get reliable averages. Here are the results:

Write Operations (Data Insertion)

Operation	MySQL	MongoDB	MongoDB Advantage
Weather Data Insert	56.7ms	19.6ms	65.4% faster
Wait Times Insert	59.2ms	19.3ms	67.4% faster
Attendance Insert	57.2ms	19.3ms	66.2% faster
Schedule Insert	57.7ms	28.4ms	50.7% faster

Takeaway: MongoDB consistently outperformed MySQL for write operations, often by more than 2:1 ratios.

Read Operations (Analytics Queries)

Query Type	MySQL	MongoDB	Winner
RQ1: Average wait times by attraction	52.6 seconds	1.0 seconds	MongoDB (98.1% faster)
RQ2: Attendance by weather conditions	413ms	20.7 seconds	MySQL (98% faster)
RQ3: Wait times vs weather correlation	1h 12m 37s	5ms*	MongoDB
RQ4: Holiday vs regular attendance	66.3ms	58.5ms	MongoDB (11.7% faster)

*MongoDB query completed quickly, MySQL query failed after 4+ hours

What These Results Actually Mean

MongoDB's Strengths Revealed

Simple Aggregations: The 98% performance advantage in RQ1 shows MongoDB's aggregation pipeline excels at straightforward grouping and averaging operations.
Complex Time-Based Queries: RQ3's dramatic difference (MySQL took over an hour, MongoDB completed in milliseconds) demonstrates MongoDB's superiority for complex temporal correlations.
Write-Heavy Workloads: Consistent 50-67% faster write performance makes MongoDB ideal for real-time data ingestion scenarios.

MySQL's Surprising Victory

RQ2 (weather-based attendance analysis) was 98% faster in MySQL. This query required complex temporary table operations and multiple data source correlations – an area where SQL's mature optimization still shines.

The Technical Why Behind the Performance

MongoDB Advantages:

No JOIN overhead: Embedded documents eliminate expensive table joins
Optimized aggregation pipeline: Purpose-built for analytical workloads
Flexible indexing: Better suited for document-based queries
Schema flexibility: No rigid structure constraints during writes

MySQL Advantages:

Mature query optimization: Decades of SQL optimizer improvements
Efficient temporary operations: Better handling of complex intermediate results
Memory management: Superior for certain multi-table operations

Real-World Application Insights

Based on our findings, choose:

MongoDB when you have:

High-frequency data ingestion (IoT sensors, real-time analytics)
Time-series data analysis
Simple to moderate aggregation needs
Schema evolution requirements

MySQL when you have:

Complex multi-source data correlations
Heavy use of temporary tables and complex JOINs
Mature application ecosystems expecting SQL
Strict consistency requirements

The Unexpected Learning: Context Matters

The most valuable insight wasn't that one database is universally better – it's that workload characteristics determine the winner. MongoDB dominated write operations and simple aggregations by massive margins, while MySQL excelled at complex relational operations.

Performance Optimization Lessons

Index Strategy: Both databases benefited equally from proper indexing on date fields and frequently queried attributes.
Query Design: MongoDB's aggregation pipelines required different thinking than SQL, but often resulted in more maintainable code.
Hardware Considerations: Even on modest hardware (HDD storage), the performance differences were dramatic, suggesting they'd be even more pronounced on modern SSD systems.

Bottom Line for Database Selection

Don't choose a database based on hype or familiarity alone. Our Disneyland data analysis proved that:

Write-heavy applications: MongoDB provides substantial advantages
Complex analytical queries: Results vary dramatically by query type
Mixed workloads: Consider using both databases for different use cases

The 98% performance differences we observed aren't edge cases – they represent real-world scenarios that could mean the difference between a responsive application and one that frustrates users.

This performance analysis was conducted as part of a Modern Database Systems course at TH Köln. The complete benchmark code and query implementations are available here for those interested in replicating these tests.

eBPF vs Sidecar Monitoring: What We Learned Building Both

Christian Holländer — Sun, 13 Jul 2025 10:25:39 +0000

This post was originally posted over on my personal website. Maybe you want to check it out [HERE].

We tried to replace sidecar monitoring with eBPF in Kubernetes. Spoiler: it didn't go as planned. Here's what we learned about hype vs reality in cloud-native monitoring, and when cutting-edge tech isn't always the answer.

Last semester, my team and I embarked on an ambitious project: comparing eBPF-based monitoring with traditional sidecar proxy monitoring in Kubernetes clusters. What started as academic curiosity turned into a deep dive into kernel programming, developer experience, and the realities of cutting-edge technology adoption.

The Promise of eBPF

Extended Berkeley Packet Filter (eBPF) has been making waves in the cloud-native world. The promise is compelling: instead of deploying a sidecar container in every pod to monitor network traffic, you can run a single eBPF program in the kernel that observes everything on the node. It sounds like magic—lower resource overhead, better security visibility, and simplified deployments.

But is it really better? That's what we set out to discover.

The Traditional Approach: Sidecar Proxies

Before diving into eBPF, let's talk about how monitoring typically works today. The sidecar pattern has become the go-to approach for microservice monitoring. Tools like Envoy proxy sit alongside your application in the same pod, intercepting all network traffic and providing rich telemetry.

The good parts:

Well-understood deployment patterns
Rich ecosystem of tools and integrations
Isolated from the host system
Language and framework agnostic

The not-so-good parts:

Resource overhead multiplied across every pod
Additional complexity in pod configurations
Potential single points of failure
Network latency from additional hops

Our eBPF Experiment

We decided to build two functionally identical network monitors: one using the traditional sidecar approach and another using eBPF. Our goal was simple—track HTTP request timing and response sizes for services communicating in a Kubernetes cluster.

The Reality Check

Here's where things got interesting (read: frustrating). While the sidecar implementation was straightforward, the eBPF version became a lesson in humility.

We chose Rust with the Aya framework, hoping to avoid the typical C development complexity associated with eBPF. The initial setup was smooth—Aya's templates got us started quickly. But implementing HTTP monitoring? That's where we hit the wall.

The Technical Challenges

Memory Constraints: eBPF programs are limited to a 512-byte stack. Try parsing HTTP payloads with that constraint. Every function call needs to be carefully designed to avoid stack overflow.

The Verifier: eBPF's safety verifier is both a blessing and a curse. It prevents crashes and security issues, but it's incredibly strict about memory access patterns. We spent countless hours fighting "invalid memory access" errors even with proper bounds checking.

Limited Debugging: Forget about your favorite debugger. eBPF debugging involves a lot of bpf_printk() statements and careful reading of verifier logs. The development experience feels like programming in the 1990s.

Ecosystem Maturity: While there are excellent eBPF tools like Pixie and Cilium, rolling your own solution requires deep kernel knowledge. The learning curve is steep, and the documentation assumes significant background knowledge.

What We Actually Discovered

After weeks of development, we had to face facts: we couldn't complete our eBPF HTTP monitor in the timeframe. But this "failure" taught us valuable lessons.

eBPF Isn't Magic

The hype around eBPF is real, but it's not a silver bullet. It excels at:

Low-level network analysis
System-wide visibility
Performance monitoring
Security enforcement

But for application-layer monitoring like HTTP request tracing? The traditional approaches are often more practical.

The Developer Experience Gap

Moving from sidecar configuration to eBPF programming shifts the burden from operations teams to developers. This isn't necessarily bad, but it requires different skills. You're essentially doing kernel programming, which most application developers haven't done since their systems programming course.

When to Choose What

Based on our experience, here's our take:

Choose eBPF when:

You need system-wide visibility
Performance overhead is critical
You're building infrastructure tools
Your team has kernel programming expertise

Stick with sidecars when:

You need application-layer insights
Your team values quick iteration
You want mature tooling and support
Operational simplicity matters

The Bigger Picture

Our experiment confirmed something important: technology choices aren't just about technical capabilities—they're about team capabilities, operational complexity, and long-term maintainability.

eBPF is incredibly powerful, but with great power comes great complexity. For most teams monitoring microservices, mature solutions like Envoy proxy or ready-made eBPF tools like Pixie offer the best balance of capability and usability.

Lessons Learned

Prototype early: We should have built a minimal eBPF program first to understand the constraints before committing to a complex implementation.
Leverage existing tools: Unless you have specific requirements, using battle-tested solutions like Cilium or Pixie is probably smarter than rolling your own.
Consider the total cost: The "cost" of a technology includes development time, debugging complexity, and ongoing maintenance—not just runtime overhead.
Know your use case: eBPF shines for infrastructure and low-level monitoring, but application-layer observability might be better served by traditional approaches.

What's Next?

While our eBPF monitor didn't cross the finish line, the experience was invaluable. We gained deep insights into kernel programming, network monitoring, and the practical challenges of adopting cutting-edge technology.

eBPF is undoubtedly the future of many aspects of systems programming. But like any powerful technology, it requires careful consideration of when and how to apply it. Sometimes the boring, well-understood solution is exactly what you need.

For teams considering eBPF for monitoring, my advice is simple: start with existing tools, understand your specific requirements, and be prepared for a steep learning curve if you decide to build custom solutions.

The future of cloud-native monitoring is exciting, but it's built on a foundation of understanding both the possibilities and the trade-offs of the tools at our disposal.

This post is based on research conducted as part of a university project exploring eBPF applications in Kubernetes environments. While our implementation didn't reach completion, the insights gained about technology adoption and developer experience proved invaluable.

How to create a shared Prettier configuration

Christian Holländer — Fri, 14 Oct 2022 13:13:25 +0000

This post was originally posted over on my personal website. Maybe you want to check it out [HERE].

Keeping configs for styling and linting tools consistent across multiple projects can be challenging. Many tools support shared configs, which are created once and used everywhere. This article will discover how to create a shared configuration for prettier.

Motivation

Recently we decided, that we want to have a common styling on how to write our Typescript code. This would make it easier for us to read and understand code others had written or even that we have written ourselves a few months ago. Therefore we agreed on integrating Prettier. An opinionated code formatter.

When we first adopted prettier on all our dozens of projects we copy/pasted the configuration from one project to the other. As we updated the config to fit our needs we were faced with inconsistent options in our projects. So we needed to figure out, how to change the prettier options globally for all our projects at the same time. Luckily the prettier maintainers got you covered. They already thought of that problem and provide a native way to share the config across multiple projects by creating a separate npm package. (Sharing Configurations)

In this guide, I want to show you how we structured our shared config to meet several projects with different prettier plugins, like the phenomenal Tailwind Prettier plugin. But also to make it extensible if a project needs some special config options only for this specific project.

Get Started

First of all, we need to initialize our repository. As I love typescript I wanted that the shared config itself is written in typescript and gets transpiled to javascript through a built-step. I will do this by using Rollup.js, but Webpack should do the trick as well. So let’s get started..

Installing Typescript should be straightforward by running npm i -D typescript and creating a tsconfig.json in the project root. I am using this one:

{
  "compilerOptions": {
    "target": "es6",
    "module": "ESNext",
    "strict": true,
    "importHelpers": true,
    "moduleResolution": "node",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "sourceMap": true,
    "outDir": "dist",
    "declaration": true,
    "declarationDir": "dist/types",
    "declarationMap": true,
    "resolveJsonModule": true,
    "baseUrl": ".",
    "typeRoots": [
      "node_modules/@types"
    ],
    "lib": [
      "es2015",
      "es2017"
    ]
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

Now I want to initialize the Rollup.js setup by adding the rollup.config.js:

import excludeDependenciesFromBundle from 'rollup-plugin-exclude-dependencies-from-bundle';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from 'rollup-plugin-typescript2';
import { visualizer } from 'rollup-plugin-visualizer';

// eslint-disable-next-line @typescript-eslint/no-var-requires
const packageJson = require('./package.json');

export default {
    input: 'src/index.ts',
    inlineDynamicImports: true,
    output: [
        {
            file: packageJson.main,
            format: 'cjs',
            exports: 'default',
            sourcemap: true,
        },
    ],
    plugins: [
        excludeDependenciesFromBundle(),
        resolve(),
        commonjs(),
        typescript({
            useTsconfigDeclarationDir: true,
        }),
        visualizer({
            filename: 'package-deps.html',
            template: 'sunburst',
            gzipSize: true,
            brotliSize: true,
        }),
    ],
};

I will skip the installation of the necessary dependencies, as I think you already know how to do this when you are interested in creating a shared prettier config ;)

Now we are finally ready to actually create the shared config in our src folder:

import type { Config } from 'prettier';

const defaultConfig: Config = {
    singleQuote: true,
    bracketSameLine: true,
    tabWidth: 4,
    plugins: [],
    overrides: [
        {
            files: '**/*.{json,yml,yaml}',
            options: {
                tabWidth: 2,
            },
        },
        {
            files: '**/*.{yml,yaml}',
            options: {
                singleQuote: false,
                bracketSpacing: false,
            },
        },
    ],
};

export default defaultConfig;

Last but not least I want to show you a cool little trick to use the just-built config right in this project. When do this by creating a prettier.config.js file in our project root. In there we put the following content:

/** @type {import('prettier').Options} */
module.exports = require('./dist/prettier-config');

We are actually just importing our build module and re-export it so our prettier command can find it. But note: You need to build before you can apply the changes of the shared config to the project because there is a built-step involved!

Automatic Package Releases using Semantic-Release

Christian Holländer — Sat, 24 Sep 2022 21:08:23 +0000

This post was originally posted over on my personal website. Maybe you want to check it out [HERE].

Writing the release notes and Changelog manually is a time-consuming and complicated task. And then you need to push your new release to your desired Package-registry like NPM or Packagist. Fortunately, there is a better way to do this. Join me in discovering an alternative.

When you already maintained an open-source package or developed a package at work, you might know how complicated the job of releasing a new version can be. Most of the time the process contains the following steps:

Scim all Commits, Issues, and PRs to see what changed
Create a list of the previously collected changes for your Changelog and Release-Notes
Decide if you want to create a patch, minor or major release (and probably have to ask the author of the changes)
If your package provides the version to its users, update it
Add a new Git tag to the repository and let your CI/CD build one last time
Push the newly built package to the Registry of your liking (don't forget to authenticate 😉)

Fortunately, there is an easy way to automate all of this. It's called CI/CD. Personally, I use Gitlab CI/CD as all my Code is hosted on Gitlab. But Github Actions and other providers should work similarly. So now we need to think about how we can achieve all our tasks in an automated manner. We as developers are lazy people, so writing a bunch of bash scripts all ourselves is not really an option. Luckily there is a tool we can use to help out:

Semantic-Release

Semantic-Release is a tool that automates most of the hard tasks needed to release a new version of our package. It actually can also release new versions of our application, but that is a bit more difficult. Its plugin system makes it easy and extendable for multiple package managers and steps.

So let's get started:

For this example we want to publish a new NPM package as this is the easiest, to begin with.

First, install the necessary packages:

npm install -D semantic-release @semantic-release/git @semantic-release/gitlab @semantic-release/npm

Here I installed the main package semantic-release with some plugins that I need for my setup. There is a good list of official and community plugins on the documentation page of the project: https://semantic-release.gitbook.io/semantic-release/extending/plugins-list

You can also add a script section to your package.json. For me, it was actually necessary. Otherwise, I could not run the command inside my CI/CD environment. Because it was not in my PATH:

{
  "scripts": {
    "semantic-release": "semantic-release"
  }
}

Now that we can run Semantic Release, we need to configure the project so that releasing works. This is especially important if you don't want to push a package into the normal NPM registry, but want to use the GitLab registry as I do.
For this, we have to adjust the "publishConfig" in the package.json. Enter there the URL of your registry. For me, this is the project-specific URL of the GitLab registry.

{
  "publishConfig": {
    "@<package-scope>:registry": "https://gitlab.com/api/v4/projects/<gitlab-project-id>/packages/npm/"
  }
}

Do not set the private attribute in your package.json to true, even though it is an internal/private package. This will prevent Semantic-Release from publishing your package to ANY registry.

After that, we still need to authenticate against our internal registry. For this, we use the so-called .npmrc file. In this file, we configure our package scope with a target URL and a personal access token for authentication. I found it easiest to put the scope definition directly into the repo. The token setting must never happen in the repo, otherwise, you expose the token to possibly unauthorized third parties.

@<package-scope>:registry=https://gitlab.com/api/v4/projects/<gitlab-project-id>/packages/npm/

Then you can set your personal access token for local development in your ~/.npmrc file. This way you can also authenticate in other projects on your machine and you do not accidentally commit your token to the repo. You can do it like this:

//gitlab.com/api/v4/packages/npm/:_authToken=<access-token>

Yes the syntax with the // at the beginning is correct. It is rather strange, but this is how it is.

As we also need the token in our CI/CD we need to set this inside our pipeline job. I did this like so:

  before_script:
    - echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/">.npmrc
    - echo "${CI_API_V4_URL#https?}/packages/npm/:_authToken=${CI_JOB_TOKEN}">>.npmrc

I completely overwrite the .npmrc with variables provided by the CI environment. The nice thing about GitLab is, that it already provides all necessary tokens and URLs. I'll show the complete Job-configuration later on.

Now that we configured everything for NPM to publish a package, we also need to configure Semantic-Release so that we can trigger the releases correctly. Therefore we can use a variety of file formats. The most popular ones are JSON and Javascript. You can find out more here. For this demo I chose release.config.js cause it gives us the most dynamic way to configure Semantic-Release:

/** @type {import("semantic-release").Options } */
module.exports = {
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/gitlab",
    "@semantic-release/npm"
  ],
  "branches": [
    "+([0-9])?(.{+([0-9]),x}).x",
    "main",
    "next",
    "next-major",
    {
      name: "beta",
      prerelease: true,
    },
    {
      name: "alpha",
      prerelease: true,
    }
  ],
};

Configuring the branches is currently only necessary because we already use the new git naming for our default branch "main". If you are still using "master", you won't need to configure them.

If you are using TypeScript like me, you can also install @types/semantic-release and use the shown type doc, to get autocompletion in most IDEs.

Add CI job

Last but not least we need to configure our already mentioned CI-Job. This depends on your environment. As I am using Gitlab-CI/CD I can only show how this works:

release:
  stage: release
  image: node:18.7
  only:
    - main
  before_script:
    - echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/">.npmrc
    - echo "${CI_API_V4_URL#https?}/packages/npm/:_authToken=${CI_JOB_TOKEN}">>.npmrc
  script:
    - npm run semantic-release

One thing you will also need to set is an environment Token called: GITLAB_TOKEN. This is needed for the Gitlab-plugin and to be able to upload Releases to Gitlab. You can find these in the left menu under Deployments > Releases.

Workflow

To use this automatic release setup, you need to use a special Commit syntax. It is actually quite simple, but you need to memorize all the different keys. Like if you write a commit message like feat: some dope new feature, Semantic-Release will trigger a minor update of your package. If you use fix: some small bug fix, it will trigger a patch release. You can also always do a major release by adding BREAKING CHANGE: Description what changes. to your commit. For example:

feat: we added a non backward compatible change

BREAKING CHANGE: Please now use this and that.

Conclusion

This should be it. Now you are all set to automatically release your package with the special Commit-Syntax.
If you want to know more I highly suggest reading through the amazing documentation. I have already mentioned it here and there throughout this post.

And now the only thing left is to say thank you for reading!