Calaf 2025.9.0

Calaf

---

Calaf is a command-line tool for managing Calendar Versioning (CalVer) of .NET projects, written in F#.

Table of Contents

• Features
• Requirements
• Versioning Scheme
• Quick Start
• Commands Reference
• Changelog Generation
• Further Use
• License
• Special Thanks

Features

• Automatic Calendar Versioning based on the current UTC date
• Support for stable, alpha, beta, rc and nightly release types
• Git integration with automatic tagging and aversion commit for new versions
• Automatic CHANGELOG.md generation based on Conventional Commits
• Works with C#/F# project files (*.csproj/*.fsproj)
• Generates versions compatible with Semantic Versioning 2.0.0
• Tool installation via the dotnet CLI

Requirements

• .NET 8.0 or later
• Git (required for automatic commiting and tagging when creating new versions)

Versioning Scheme

Calaf implements a Calendar Versioning (CalVer) scheme that is compatible with Semantic Versioning 2.0.0. This ensures that versions are chronological, sortable, and widely supported.

Format: YYYY.MM[.MICRO][-BUILD.FORMAT]

Core Components:

YYYY - Full year (required)

• Examples: 2001, 2025, 2150
• Range: 1 to 9999

MM - Month number (required)

• Examples: 1, 6, 12
• Range: 1 to 12

MICRO - Micro number within the month (optional)

• Examples: 1, 2, 3
• Range: 1 to 4294967295

Pre-release Components:

BUILD.FORMAT - Pre-release build identifier with a specific format suffix to indicate non-stable builds:

• Alpha releases: alpha.NUMBER

  • Example: 2025.9.1-alpha.1
  • Range NUMBER: 1 to 4294967295

• Beta releases: beta.NUMBER

  • Example: 2025.9.1-beta.1
  • Range NUMBER: 1 to 4294967295

• Release Candidate: rc.NUMBER

  • Example: 2025.9.1-rc.1
  • Range NUMBER: 1 to 4294967295

• Nightly builds: 0.nightly.DAY.NUMBER

  • The leading 0 ensures that nightly builds have lower precedence than other pre-release builds like alpha, beta.
  • DAY: The day of the month
  • NUMBER: A sequential number for builds on the same day
  • Example: 2025.9.1-0.nightly.30.1
  • Range NUMBER: 1 to 4294967295

• Alpha nightly builds: alpha.ALPHA_NUMBER.DAY.NIGHTLY_NUMBER

  • Example: 2025.9.1-alpha.1.30.1

• Beta nightly builds: beta.BETA_NUMBER.DAY.NIGHTLY_NUMBER

  • Example: 2025.9.1-beta.1.30.1

• Release Candidate nightly builds: rc.RC_NUMBER.DAY.NIGHTLY_NUMBER

  • Example: 2025.9.1-rc.1.30.1

Version Precedence

Versions are compared according to SemVer 2.0.0 rules. The following list shows an example of version progression from lowest to highest precedence:

1. 2025.9.1-0.nightly.30.1 (Nightly)
2. 2025.9.1-alpha.1 (Alpha)
3. 2025.9.1-alpha.1.30.1 (Alpha Nightly)
4. 2025.9.1-alpha.2 (Later Alpha)
5. 2025.9.1-beta.1 (Beta)
6. 2025.9.1-beta.1.30.1 (Beta Nightly)
7. 2025.9.1-beta.2 (Later Beta)
8. 2025.9.1-rc.1 (Release Candidate)
9. 2025.9.1-rc.1.8.1 (Release Candidate Nightly)
10. 2025.9.1 (Stable Release)

Quick Start

1. Installation:

dotnet tool install -g Calaf

2. Add an initial version to your project (C# / F#) file(s) (*.csproj or *.fsproj):

<PropertyGroup>
    <Version>2025.9</Version>
</PropertyGroup>

3. Generate a stable Calendar Version:

calaf make stable

Commands Reference

calaf make <type>

Synopsis:

calaf make <stable|alpha|beta|rc|nightly>

Description: Generates and applies a new Calendar Version to all .csproj and .fsproj files in the current directory. Automatically creates Git commit and tag if repository is detected.

Automatic Changelog Generation: When calaf make is run in a Git repository, it also automatically generates or updates a CHANGELOG.md file. The tool analyzes commits since the last version tag that follow the Conventional Commits specification.

• Commits like feat(scope): description are added under a ### Features section, grouped by scope.
• Commits like fix(scope): description are added under a ### Bug Fixes section, grouped by scope.
• Commits with a ! after the type/scope (e.g., feat(api)!:) are added under a ### Breaking Changes section.

Arguments:

Argument	Description
stable	Stable release. Creates a production-ready version.
alpha	Alpha release. Creates an early pre-release version for testing. Increments the alpha number. Alpha numbering starts from 1 and increments with each new alpha release.
beta	Beta release. Creates a pre-release version for testing. Increments the beta number. Beta numbering starts from 1 and increments with each new beta release.
rc	Release Candidate. Creates a version for final testing before stable release. Increments the rc number. Rc numbering starts from 1 and increments with each new rc release.
nightly	Nightly (development) build. Creates a development build version. Uses the current day and an incremental number that's starts from 1 for that day.

Examples:

Stable Release

Creates a production version based on current UTC date on running system (System.DateTimeOffSet.UtcNow). 2025.9 → 2025.9.1

• Command:

calaf make stable

• Output:

Version applied: 2025.9.1

• Project file(s) change:

<Version>2025.9</Version>


<Version>2025.9.1</Version>

Alpha Release

Creates an early pre-release version. 2025.9.1 → 2025.9.1-alpha.1

calaf make alpha 

• Output:

Version applied: 2025.9.1-alpha.1

• Project file(s) change:

<Version>2025.9.1</Version>


<Version>2025.9.1-alpha.1</Version>

Beta Release

Creates a pre-release version. 2025.9.1 → 2025.9.1-beta.1

calaf make beta 

• Output:

Version applied: 2025.9.1-beta.1

• Project file(s) change:

<Version>2025.9.1</Version>


<Version>2025.9.1-beta.1</Version>

RC Release

Creates a release candidate version for final testing before stable release. 2025.9.1 → 2025.9.1-rc.1

calaf make rc

• Output:

Version applied: 2025.9.1-rc.1

• Project file(s) change:

<Version>2025.9.1</Version>


<Version>2025.9.1-rc.1</Version>

Nightly Build

Creates a development build with daily identifier. 2025.9.1 → 2025.9.2-0.nightly.27.1

calaf make nightly

• Output:

Version applied: 2025.9.2-0.nightly.27.1

Note: Subsequent runs on the same day increment the build number: 2025.9.2-0.nightly.27.2, 2025.9.2-0.nightly.27.3, etc.

Project file change:

<Version>2025.9.1</Version>


<Version>2025.9.2-0.nightly.27.1</Version>

Note: Nightly from Alpha

You can create nightly builds from existing alpha versions. 2025.9.1-alpha.1 → 2025.9.1-alpha.1.27.1

• Output:

Version applied: 2025.9.1-alpha.1.27.1

Project file change:

<Version>2025.9.1-alpha.1</Version>


<Version>2025.9.1-alpha.1.27.1</Version>

Note: Nightly from Beta

You can create nightly builds from existing beta versions. 2025.9.1-beta.1 → 2025.9.1-beta.1.27.1

• Output:

Version applied: 2025.9.1-beta.1.27.1

Project file change:

<Version>2025.9.1-beta.1</Version>


<Version>2025.9.1-beta.1.27.1</Version>

Note: Nightly from Release Candidate

You can create nightly builds from existing rc versions. 2025.9.1-rc.1 → 2025.9.1-rc.1.27.1

• Output:

Version applied: 2025.9.1-rc.1.27.1

Project file change:

<Version>2025.9.1-rc.1</Version>


<Version>2025.9.1-rc.1.27.1</Version>

Changelog Generation

Calaf automatically maintains CHANGELOG.md during calaf make:

• Commit range: from the last version Git tag to HEAD. If no tag exists, all commits are considered.
• Source: commits conforming to Conventional Commits are categorized. The format type(scope): description is supported, where (scope) is optional.
• Categories:
  • ### Breaking Changes: commits with ! after the type/scope (e.g., feat(api)!: drop support for old format).
  • ### Features: commits with feat:.
  • ### Bug Fixes: commits with fix:.
• File handling: creates CHANGELOG.md if missing; prepends the new release entry if present.
• Git integration: CHANGELOG.md is staged together with project file updates and included in the version commit and tag.

Example entry:

## 2025.9.1 - 2025-09-27

### Breaking Changes
- **versioning:** change version format to YYYY.MM[.MICRO][-BUILD.FORMAT]

### Features
- **core:** add RC pre-release support
- **versioning:** change version format to YYYY.MM[.MICRO][-BUILD.FORMAT]

### Bug Fixes
- **fs:** correct content duplication in markdown writer

Further Use

The following example illustrates how to integrate Calaf into a CI/CD pipeline for automated Calendar Versioning:

jobs:
    release:
        name: Release
        runs-on: ubuntu-latest
        steps:
          - name: Checkout code
            uses: actions/checkout@v4
            with:
              # Fetch all history for accurate version calculation
              fetch-depth: 0
  
          - name: Install Calaf
            run: dotnet tool install -g Calaf
  
          - name: Make a new stable version
            id: versioning
            run: calaf make stable
            continue-on-error: false
            
          - name: Push version changes
            run: |
              git push origin ${{ github.ref_name }}
              git push origin --tags

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Special Thanks

Special thanks to Anna Mazhaieva for designing the graphic assets used in this project.