MulleObjC-startup Versioning Scheme: Semantic Versioning Implementation

MulleObjC-startup follows strict semantic versioning (MAJOR.MINOR.PATCH) defined in CMakeLists.txt and synchronized with Git tags to ensure consistent release management across build systems and downstream dependencies.

The MulleObjC-startup repository provides essential initialization code for the Mulle Objective-C runtime. Understanding its versioning scheme is critical for maintaining compatibility in downstream projects and CI/CD pipelines. This guide examines how MulleObjC-startup implements semantic versioning across its CMake build system, source code, and release artifacts.

Semantic Versioning Structure in MulleObjC-startup

MulleObjC-startup adheres to the classic MAJOR.MINOR.PATCH semantic versioning format. Three numeric components, separated by dots, define the release identity.

Major version changes (transitioning from 0 to 1) are reserved for breaking API modifications. While the library maintains a 0.x version number, it indicates a pre-1.0 stable line where the API may still evolve.

Minor version increments introduce new, backward-compatible features. These additions extend functionality without breaking existing consumer code.

Patch version increments address bug fixes, security patches, or trivial adjustments that do not add new functionality.

Where Version Information Is Stored

The MulleObjC-startup versioning scheme relies on multiple synchronized locations to ensure consistency across build and distribution channels.

CMakeLists.txt as the Source of Truth

The primary version definition resides in the root CMakeLists.txt file. The CMake project() command establishes the canonical version string used throughout the build system.

project( MulleObjC-startup VERSION 0.20.7 LANGUAGES C )

This declaration sets the PROJECT_VERSION variable, which CMake uses for packaging and for generating configuration headers.

Git Tags for Release Management

Release versions are permanently marked in the Git repository through annotated tags. The tag names exactly mirror the CMake version strings.

Key tag references include:

• .git/refs/tags/0.20.7
• .git/refs/tags/0.27.0

These tags appear on the GitHub Releases page and serve as the exact version strings referenced by CI systems and downstream dependency managers.

Generated Configuration Headers

CMake processes the template file cmake/share/MulleObjC-startup-config.h.in to generate MulleObjC-startup-config.h. This header exposes the version to client code through a preprocessor macro.

The generated header contains:

#define MULLE_OBJC_STARTUP_VERSION "0.20.7"

Source files such as src/MulleObjC-startup.m include this header to access version information at compile-time.

Release Documentation

The RELEASENOTES.md file maintains a human-readable changelog. Each release receives a dedicated section header using the version number.

Example entry:

### 0.20.7

This documentation ensures users can track changes between specific semantic versions.

Practical Examples for Developers

Querying the Version in C Code

Client applications can determine the linked version of MulleObjC-startup at runtime by checking the generated version macro.

#include <MulleObjC-startup/MulleObjC-startup.h>
#include <stdio.h>

int main(void)
{
    printf("MulleObjC-startup version: %s\n",
           MULLE_OBJC_STARTUP_VERSION);
    return 0;
}

The macro MULLE_OBJC_STARTUP_VERSION expands to the string defined in the CMake project configuration.

Enforcing Version Requirements in CMake

Downstream projects can specify minimum version requirements when locating the package. CMake validates the installed version against the semantic version constraint.

# In a consumer's CMakeLists.txt

find_package(MulleObjC-startup 0.20 REQUIRED)

# The call will fail if the installed startup library is older than 0.20.x

This mechanism relies on the PROJECT_VERSION defined in the upstream CMakeLists.txt.

Creating a New Release Tag

Maintainers must synchronize Git tags with the CMake project version. The following commands create an annotated tag matching the version declared in CMakeLists.txt.

# After bumping the version in CMakeLists.txt

git tag -a 0.27.0 -m "Release 0.27.0 – new loader support"
git push origin 0.27.0

The tag name must exactly match the version string used in the project(... VERSION ...) declaration to maintain consistency across the versioning scheme.

Version Compatibility Guidelines

When depending on MulleObjC-startup, observe these semantic versioning rules:

• Major version zero (0.x.y) indicates the library is in a pre-1.0 stable line. While functional, breaking changes may occur when transitioning to 1.0.0.
• Minor version bumps guarantee backward compatibility. You can safely upgrade from 0.20.0 to 0.27.0 without modifying client code.
• Patch version bumps contain only bug fixes. These are always safe to apply immediately.

The single source of truth remains the CMakeLists.txt file, with all other references (Git tags, headers, documentation) deriving from this definition.

Summary

• MulleObjC-startup uses semantic versioning (MAJOR.MINOR.PATCH) to communicate compatibility and change impact.
• The canonical version lives in CMakeLists.txt within the project() command.
• Git tags (e.g., 0.20.7, 0.27.0) mirror the CMake version to mark release points.
• The MULLE_OBJC_STARTUP_VERSION macro exposes the version to C code via generated headers.
• Minor and patch updates maintain backward compatibility; major updates (including the eventual 0→1 transition) signal breaking changes.

Frequently Asked Questions

What versioning scheme does MulleObjC-startup use?

MulleObjC-startup follows semantic versioning with a three-part number format: MAJOR.MINOR.PATCH. This scheme is implemented in the CMake build system and synchronized with Git tags to ensure consistent version identification across source code and binary distributions.

How do I check which version of MulleObjC-startup is installed?

You can query the version at compile-time by checking the MULLE_OBJC_STARTUP_VERSION macro defined in the generated MulleObjC-startup-config.h header. In CMake-based projects, you can also verify the version through the find_package command, which validates the installed version against your project's requirements.

What does the 0.x version number indicate?

The 0.x version line indicates that MulleObjC-startup is in a pre-1.0 stable state. While the library is functional and maintained, the major version zero signals that breaking API changes may occur when the project eventually transitions to version 1.0.0. Minor and patch releases within the 0.x line still follow semantic versioning rules for backward compatibility.

How do I specify a minimum version requirement in CMake?

Use the find_package command with a version constraint in your CMakeLists.txt. For example, find_package(MulleObjC-startup 0.20 REQUIRED) ensures that CMake will only accept version 0.20.0 or higher (such as 0.27.0) while rejecting older releases. This mechanism relies on the version defined in the upstream CMakeLists.txt project declaration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}