Follow me on:

Semver vs. Calver and Why I Use Both
Published by Mike Staszel on April 3, 2021

I began properly versioning the software I write recently. I’m working on a Python package that I hope others will use. My goal is to iterate and release new features and fixes over time, but I need a way to signal to the world that a new version is available.

Why You Should Version Your Code

  • It’s a best practice.
  • It makes you think about supporting users of your code.
  • It only takes a few extra minutes during the software development lifecycle.
  • You should version your code if you ever want to share it with others.

Why You Should NOT Version Your Code

  • It’s a personal project. Unless your goal is to learn how to properly version your software, this can be a distraction.
  • During the very beginning of a project. Making a decision about versioning should happen when you’re ready to share something with others — not before.
  • Git and other version control systems version code for you. You can extend this with tags and releases.

Two popular version schemes are Semantic Versioning and Calendar Versioning. Each have its strengths and weaknesses.

Semantic Versioning

  • Here’s the guide — the summary is exceptionally clear: https://semver.org [https://semver.org/]
  • This method is more common and you’ve seen it. A version number is based on changes in the software.
  • Examples of this: 1.0.0, 1.0.1, 1.1.0, 2.0.0.

Calendar Versioning

  • Here’s the guide: https://calver.org [https://calver.org/]
  • This method uses the calendar to version software.
  • Microsoft is starting to do this with Windows 10 — versions and updates are named after years and months they’re released.
  • This is a little bit more loosely defined than Semantic Versioning.
  • Examples: 2020.6, 2021.01.01, 21.04.

When to Use Which

I use both of these approaches depending on what kind of application is being developed.

Even if you use neither of these approaches, consider using git tags, they’re very lightweight and you’ll thank yourself later. It’s like an easy-to-see snapshot your code at a point in time.

For “rolling” and fast-moving applications, I use CalVer:

  • An example of this can be something like an ETL pipeline that’s continuously being modified.
  • Easier to reason about and set up — it’s just a date.
  • This is nicer than using only git for version history.

For slower-moving or shared components and libraries, use SemVer:

  • Releases happen infrequently.
  • Older releases are supported with patches.
  • Great for shared libraries.
  • Useful for when you want to provide some guarantees about compatibility to others.

Featured Posts

  1. A typical modern Spark stack nowadays most likely runs Spark jobs on a Kubernetes cluster, especially for heavy usage. Workloads are moving away from EMR on EC2 to either EMR on EKS or open-source Spark on EKS. When you’re running Spark on EKS, you probably want to scale your Kubernetes nodes up and down as you need them. You might only need to run a few jobs per day, or you might need to run hundreds of jobs, each with different resource requirements.

    aws development kubernetes

  2. Hi there, I’m Mike. 🔭 I’m currently working on big data engineering with Spark on k8s on AWS at iSpot.tv. 🌱 I’m focusing on mentoring and coaching my team to improve their skills and release awesome products. 🌎 I occasionally write blog posts about software engineering and other topics. Management and Software Engineering I consider myself to be a software engineer at heart. Nowadays I’m trying to do less code-writing and more of everything else: