version-aligner

A small development tool to keep application versions aligned with Git tags and changelog entries.

The version-aligner works particularly well with standardized PHP package structures such as those defined by pds/skeleton.

Why?

Releases can have more than one version source.

For example, a CLI application might have its version defined in the application itself, while the release version is represented by a Git tag and documented in CHANGELOG.md.

It is easy to update the Git tag and changelog while forgetting to bump the version in the application.

That has happened to me several times.

The result is a release where the repository says one thing, while the application reports another:

Git tag       v1.4.0
CHANGELOG.md  1.4.0
Application   1.3.0  ← forgotten

version-aligner exists to catch exactly this kind of inconsistency.

It checks whether your application's version matches the release version represented by Git and CHANGELOG.md before an outdated version reaches your users.

What it checks

version-aligner compares:

• the latest Git tag
• the latest version in CHANGELOG.md
• the version set in the application

All three versions must refer to the same release.

Installation

The version-aligner CLI can be installed through Composer.

composer require --dev stolt/version-aligner

Available commands

Check command

check compares the application's version with the latest Git tag and the latest CHANGELOG.md entry.

version-aligner check [--format=json]

Version alignment

✓ Git tag          v1.0.0
✓ CHANGELOG.md     1.0.0
✗ Application      0.9.0

Version mismatch detected.

Version alignment

✓ Git tag          v1.0.0
✓ CHANGELOG.md     1.0.0
✓ Application      1.0.0

All versions are aligned.

You can use it in pre-commit Git hooks, Composer scripts, or continuous integration workflows.

Example Composer script:

"scripts": {
   "test": "phpunit",
   ... // omitted scripts
   "version-check": "version-aligner check"
}

Evaluable outcomes of the check command are:

Scenario	Expected behavior
All versions match	Exit 0
Version mismatch	Non-zero exit
Required source missing	Clear diagnostic and non-zero exit
Git metadata unavailable	Clear diagnostic and non-zero exit

Align command

align updates the application version when it differs from the release version.

version-aligner align [--dry-run]

License

This library and its CLI are licensed under the MIT license. Please see LICENSE.md for more details.

Changelog

All noteworthy changes are documented in the CHANGELOG.md.

Contributing

If you're considering contributing to this project, have a look at this repository's CONTRIBUTING.md for more advice.