Skip to content

Releasing

How Phexium versions are numbered, documented in the changelog, and tagged.

Versioning Policy

Phexium follows Semantic Versioning:

  • Git tags carry a v prefix (v0.9.0); changelog headings do not (0.9.0).
  • While the major version is 0, the API is not frozen: breaking changes bump the minor version, everything else bumps the patch version.
  • From 1.0.0 on, standard semantics apply: breaking changes bump the major version, new features the minor, fixes the patch.

Changelog

CHANGELOG.md follows the Common Changelog convention:

  • Releases ordered latest-first, headed ## [X.Y.Z] - YYYY-MM-DD, with the version linked to its GitLab tag.
  • Changes grouped under Changed, Added, Removed, Fixed, in that order.
  • Entries written in the imperative mood, one line each, self-describing.
  • Breaking changes prefixed with **Breaking:** and listed first in their category.

Scope

The changelog covers the framework core only: src/, tools/, the installer, and the framework test and build infrastructure. Demo and starter application content, blog posts, website changes, and maintenance noise (CI tweaks, style fixes) are excluded. A demo change appears only when it demonstrates a new framework capability, phrased as that capability.

Unreleased section

As a deliberate deviation from Common Changelog (which writes entries at release time), notable changes are accumulated in an ## [Unreleased] section at the top of the file as they land on trunk. At release time, this section becomes the new version heading.

Release Process

  1. Make sure trunk is clean and up to date.

  2. Run the release gate:

    task release:all

    This chains release:fix (rector, coding standard) and release:test (all test suites, deptrac).

  3. Determine the version bump from the content of the Unreleased section (any **Breaking:** entry bumps the minor while on 0.x).

  4. In CHANGELOG.md, rename ## [Unreleased] to ## [X.Y.Z] - YYYY-MM-DD and add the version link at the bottom of the file.

  5. Commit the changelog, then tag and push:

    git tag vX.Y.Z
git push origin trunk --tags

  6. Create a GitLab release from the tag, pasting the changelog entry as release notes.

Versions and the Copy-Based Model

Phexium uses a copy-based distribution: applications own their copy of the framework and track the upstream commit SHA in .phexium-version. Tags do not change that mechanism; they provide human-readable anchors on top of it. To see what changed between your copy and a release, compare your recorded SHA against the tag:

php tools/phexium.php status    # Current upstream SHA
git log --oneline <your-sha>..vX.Y.Z

The CHANGELOG.md entry for each version summarizes the same range in human terms.