One Change, Two Versions: Speaking to Engineers and Customers at the Same Time

The latest release is a success. The team shipped a dozen bug fixes, refactored a service, and added two valuable features. Your CI/CD pipeline did its job perfectly, followed the SemVer rules, and tagged the release as v1.13.0.

Then the Product Manager sits down to write the announcement, and their heart sinks.

To a customer, v1.13.0 is meaningless noise. Is it a big update? A small patch? How is it different from the v1.12.7 they got last week? By forcing a technical, machine-readable contract onto your customers, you’ve created a communication gap.

One Number, Two Different Jobs

The problem is that we’re asking one number to talk to two completely different audiences:

• For Engineers: The version is a strict contract. 1.13.0 signals new, backward-compatible features. It's for dependency management and stability.

• For Customers: The version is a narrative. They want to know "What’s new this month?" or "What’s in the Summer release?"

Forcing these two groups to share a single number serves neither of them well. It makes engineering look overly complex to the customer and makes marketing look imprecise to the engineer.

The Solution: Dual Versioning

A modern, evidence-based versioning strategy doesn't just produce one number; it produces a set of versions tailored to the audience, all derived from the same analysis of the code.

When your pipeline analyzes a set of changes, it should generate two distinct, linked identifiers:

1. The Engineering Tag: A precise SemVer string (like v1.13.0) for Git tags and package managers. This is the machine's contract.

2. The Marketing Version: A simple, human-friendly string (like 2026.1 or February Release) for release notes and blog posts. This is the human's narrative.

Automated Metadata

You can automate this by having your pipeline generate a version metadata artifact that stores both values.

1. The Analysis: The pipeline detects a new feature.

2. The Calculation: It increments the SemVer to 1.13.0 and maps the current date to a marketing version like 2026.Q1.

3. The Output: It saves both to a JSON file that other tools can consume.

{
  "semver": "1.13.0",
  "marketing_version": "2026.Q1",
  "change_summary": "Added bulk-export feature",
  "is_breaking": false
}

Communicating with Purpose

This isn't about "vanity" numbers; it's about recognizing that the contract a machine needs is different from the story a human needs.

Your engineers get the precision required to keep the system stable, and your product team gets a clean, meaningful way to talk to customers. Because both are generated by the same automated process, they stay perfectly in sync.

The next time a release announcement feels like a math problem for your customers, it’s a sign you’re only telling half the story.