Versioning Strategy¶

eQual uses a strict and declarative versioning model centered around the VERSION file.

The versioning system is designed to provide:

strong installation traceability
deterministic maintenance branches
reproducible deployments
simplified support workflows
controlled upgrade paths
strict compatibility tracking between installations

The model intentionally avoids build-based versioning and relies directly on repository state.

Core Principles¶

VERSION as Source of Truth¶

The official version of an eQual installation is defined exclusively by the root VERSION file.

Example:

2.0.1

The VERSION file defines:

the official semantic version
the expected release lineage
the expected Git branch
the expected release tag

The VERSION file is the canonical reference for all runtime version information.

Branch Types¶

eQual uses two categories of branches.

Development Branches¶

Development branches are temporary integration branches used to prepare future releases.

Convention:

dev-x.y

Examples:

dev-2.1
dev-3.0

Development branches are used for:

feature development
refactoring
architecture changes
integration work

Development branches are temporary and are deleted once the corresponding stable release is created.

Stable Release Branches¶

Stable branches represent maintained release lineages.

Convention:

x.y.z

Examples:

2.0.1
2.1.0
3.0.0

Stable branches are used for:

production deployments
maintenance
bugfixes
security patches
client support

Each stable branch corresponds to the initial release of a maintained lineage.

Release Tags¶

Each official release must have an immutable Git tag.

Convention:

v{VERSION}

Examples:

v2.0.1
v2.0.2
v2.1.0

Tags provide:

exact reproducibility
deployment traceability
deterministic rollback capability
GitHub release compatibility

Tags are immutable snapshots of official releases.

Master Branch¶

The master branch always points to the latest recommended stable release.

Example:

master -> 2.1.0

This ensures that:

cloning master provides the latest stable version
new installations are aligned with the current recommended release
support alignment remains simple

Release Lifecycle¶

A typical release lifecycle follows this structure:

feature/*
    ↓
dev-2.1
    ↓
2.1.0
    ↓
v2.1.0
    ↓
master

After release:

dev-2.1 is deleted
2.1.0 becomes the maintained stable branch
future development resumes on:

dev-2.2

Stable Branch Lifecycle¶

A stable branch represents a maintained release lineage.

Example:

2.1.0

This branch may later produce:

v2.1.0
v2.1.1
v2.1.2

The branch itself remains unchanged:

2.1.0

while the VERSION file evolves to reflect the latest maintained release state.

Version Alignment¶

eQual defines a strict consistency model between:

the VERSION file
the active Git branch
the release tag

An installation is considered aligned when:

branch == VERSION

or when the installation runs directly from:

master

with a matching release state.

Examples:

VERSION	branch	aligned
2.0.1	2.0.1	true
2.0.3	2.0.3	true
2.0.3	master	true
2.0.3	2.0.1	false
2.0.3	dev-2.1	false
2.0.3	feature/x	false

Example of an aligned installation:

branch  = 2.0.3
VERSION = 2.0.3
tag     = v2.0.3

Example of a mismatch:

branch  = 2.0.1
VERSION = 2.0.3
tag     = v2.0.3

This situation may still function technically, but it indicates that the repository context does not match the declared release lineage and is therefore not considered a recommended or supported state.

The mismatch flag reflects this condition:

mismatch = (
    branch != VERSION
    AND
    branch != master
)

Installation Scenarios¶

The behavior of version detection depends on how eQual is installed.

1. Installation via Git (recommended)¶

Example:

git clone https://github.com/equalframework/equal

Characteristics¶

.git directory is present
full Git metadata is available

Behavior¶

The runtime can expose:

declared version
active branch
release tag
commit hash
commit date
working tree state

Example:

{
  "version": "2.0.3",
  "tag": "v2.0.3",
  "branch": "2.0.3",
  "commit": "81303632",
  "date": "2026.05.06",
  "dirty": false,
  "mismatch": false,
  "source": "git"
}

2. Installation from ZIP Archive¶

Example:

equal-2.0.3.zip

Characteristics¶

no .git directory
no local branch information

Behavior¶

The system:

reads the VERSION file
optionally resolves metadata using GitHub API

Example:

{
  "version": "2.0.3",
  "tag": "v2.0.3",
  "commit": "81303632",
  "date": "2026.05.06",
  "source": "github"
}

If no network is available:

{
  "version": "2.0.3",
  "source": "version"
}

3. Development Environments¶

Examples:

dev-2.1
feature/*
custom branches

Behavior¶

The runtime reflects:

the declared target version
the active development context
local repository modifications

Example:

{
  "version": "2.1.0-dev",
  "branch": "dev-2.1",
  "commit": "ba572ed4",
  "date": "2026.05.06",
  "dirty": true,
  "mismatch": true,
  "source": "git"
}

Retrieving Runtime Version Information¶

You can retrieve runtime version information using:

./equal.run --get=version

This command provides a unified view of:

declared release version
Git execution context
runtime repository state

Example Output¶

{
  "version": "2.0.3",
  "tag": "v2.0.3",
  "branch": "2.0.3",
  "commit": "81303632",
  "date": "2026.05.06",
  "dirty": false,
  "mismatch": false,
  "source": "git"
}

Field Description¶

`version`¶

Source: - VERSION file

Meaning: - official declared version of the installation

`tag`¶

Source: - Git or GitHub

Meaning: - immutable release identifier

Convention:

v{VERSION}

`branch`¶

Source: - Git

Meaning: - active release lineage or development context

Examples:

2.0.3
dev-2.1
feature/orm-refactor

`commit`¶

Source: - Git or GitHub

Meaning: - exact repository revision

`date`¶

Source: - Git or GitHub

Meaning: - commit date

Format:

YYYY.MM.DD

`dirty`¶

Source: - Git

Meaning: - indicates whether uncommitted local modifications exist

value	meaning
true	local modifications present
false	working tree clean

`mismatch`¶

Meaning: - indicates whether the runtime Git context matches the declared release version

value	meaning
true	inconsistent runtime context
false	aligned installation

`source`¶

Indicates how metadata was resolved.

value	meaning
`git`	local Git repository
`github`	resolved via GitHub API
`version`	VERSION file only

Interpretation Guidelines¶

Stable Production Installation¶

{
  "version": "2.0.3",
  "tag": "v2.0.3",
  "branch": "2.0.3",
  "dirty": false,
  "mismatch": false
}

This indicates:

aligned release lineage
clean repository state
supported production installation

Development Environment¶

{
  "version": "2.1.0-dev",
  "branch": "dev-2.1",
  "dirty": true,
  "mismatch": true
}

This indicates:

active development context
non-release state
local modifications

Minimal ZIP Installation¶

{
  "version": "2.0.3",
  "source": "version"
}

This provides:

minimal but sufficient release identification

Support Policy¶

eQual intentionally limits the number of supported release lines.

At any given time:

State	Support Level
N	full support
N-1	maintenance support
N-2	limited support
older	unsupported

This policy ensures:

manageable maintenance effort
predictable upgrade paths
rapid client realignment

Clients are expected to upgrade regularly.

The target model is to maintain installations reasonably close to the latest stable release line.

Release Process¶

The release process is intentionally deterministic and relies entirely on:

Git branches
Git tags
the VERSION file

General Rules¶

VERSION is the source of truth
each official release must have:
a stable branch
a matching Git tag
master always reflects the latest recommended stable release
development never occurs directly on stable branches
development branches are temporary

Standard Release Workflow¶

Example: preparing release 2.1.0.

1. Create development branch¶

git checkout -b dev-2.1

Development work occurs on:

features
refactors
architecture changes
integration work

2. Freeze development branch¶

Once stabilization begins:

no new features are merged
the branch becomes frozen for release preparation

3. Create stable release branch¶

Create the stable branch:

git checkout -b 2.1.0

Update VERSION:

2.1.0

4. Commit release state¶

git commit -a -m "Release 2.1.0"

5. Create release tag¶

git tag v2.1.0
git push origin v2.1.0

The tag represents the immutable official release snapshot.

6. Publish stable branch¶

git push origin 2.1.0

The branch now becomes the maintained stable lineage.

7. Update master¶

git checkout master
git merge 2.1.0
git push origin master

This ensures that:

master remains the recommended production reference
new installations align automatically with the latest stable version

8. Remove development branch¶

git branch -d dev-2.1

Future work resumes on:

git checkout -b dev-2.2

Patch Release Workflow¶

Patch releases occur directly on the maintained stable branch.

Example: releasing 2.1.1 from branch 2.1.0.

1. Checkout stable branch¶

git checkout 2.1.0

2. Apply fixes¶

Apply:

bug fixes
hotfixes
security patches
maintenance updates

3. Update VERSION¶

2.1.1

4. Commit patch release¶

git commit -a -m "Release 2.1.1"

5. Create patch tag¶

git tag v2.1.1
git push origin v2.1.1

6. Push updated branch¶

git push origin 2.1.0

The branch remains:

2.1.0

while the VERSION file reflects the latest release state.

Future patch releases continue on the same stable branch:

v2.1.2
v2.1.3

Versioning Strategy¶

Core Principles¶

VERSION as Source of Truth¶

Branch Types¶

Development Branches¶

Stable Release Branches¶

Release Tags¶

Master Branch¶

Release Lifecycle¶

Stable Branch Lifecycle¶

Version Alignment¶

Installation Scenarios¶

1. Installation via Git (recommended)¶

Characteristics¶

Behavior¶

2. Installation from ZIP Archive¶

Characteristics¶

Behavior¶

3. Development Environments¶

Behavior¶

Retrieving Runtime Version Information¶

Example Output¶

Field Description¶

version¶

tag¶

branch¶

commit¶

date¶

dirty¶

mismatch¶

source¶

Interpretation Guidelines¶

Stable Production Installation¶

Development Environment¶

Minimal ZIP Installation¶

Support Policy¶

Release Process¶

General Rules¶

Standard Release Workflow¶

1. Create development branch¶

2. Freeze development branch¶

3. Create stable release branch¶

4. Commit release state¶

5. Create release tag¶

6. Publish stable branch¶

7. Update master¶

8. Remove development branch¶

Patch Release Workflow¶

1. Checkout stable branch¶

2. Apply fixes¶

3. Update VERSION¶

4. Commit patch release¶

5. Create patch tag¶

6. Push updated branch¶

`version`¶

`tag`¶

`branch`¶

`commit`¶

`date`¶

`dirty`¶

`mismatch`¶

`source`¶