Operations

Markdown

Releasing & versions

How maintainers ship Externa Core versions: semver, CHANGELOG, bump checklist, and GitHub Releases.

Related

Changelog (docs) · CHANGELOG.md · .github/RELEASE_TEMPLATE.md · API 1.x compatibility · Contributing · Packagist & create-project

Version source of truth

FileRole
composer.json → versionCanonical package version
package.json → versionMust match Composer
README badge / version lineUpdate when bumping
Docs siteNo separate product version unless noted

Git tags: v + semver (examples: v1.0.0, v1.0.0-beta.4).

Semver (Externa)

Aligned with API & GraphQL 1.x compatibility:

BumpWhen
MajorBreaking Public API / GraphQL / documented operator contracts after deprecation (or security-driven breaks called out in notes)
MinorAdditive features; deprecations may be announced
PatchBug fixes, docs, non-contract hardening
Pre-release (-beta.N, -rc.N)Milestone cuts before GA; same CHANGELOG discipline

Admin UI / Inertia props are not a public API, but call out operator-visible breaks in Upgrade notes.

CHANGELOG

Keep Keep a Changelog sections under ## [Unreleased] while working on develop. At release:

  1. Move Unreleased items under ## [X.Y.Z] - YYYY-MM-DD
  2. Refresh compare links at the bottom of CHANGELOG.md
  3. Leave a fresh empty Unreleased section

Cut a release (checklist)

Who ships

Maintainers merge the release PR, create the git tag, and publish the GitHub Release. Agents may open the develop → main release PR (full body + assignee) and stop there — they must not merge to main, tag, or run gh release create unless explicitly asked.

  1. Milestone issues Done; CI green on develop
  2. Bump composer.json + package.json (+ README version line)
  3. Finalize CHANGELOG.md for this version
  4. Open PR develop → main (release PR); assignee + milestone labels — do not auto-merge
  5. Maintainer merges; then tags vX.Y.Z on main
  6. Maintainer publishes GitHub Release from tag — paste from .github/RELEASE_TEMPLATE.md (Added / Fixed / Breaking / Upgrade)
  7. Board: set Status to the matching Released … option when applicable
  8. Packagist auto-update should pick up the new tag — verify on packagist.org (submit runbook) · docs deploy as usual

Shipped: externa-core v1.0.0-beta.4 (2026-09-17) on Packagist. GA: externa-core v1.0.0 — human merges the release PR, tags, and confirms Packagist. Docs site for this cut: 1.1.1. See Packagist status.

GitHub Release notes

Use the repo template sections:

  • Highlights
  • Added / Changed / Fixed / Deprecated / Removed · Breaking / Security
  • Upgrade notes
  • Links (CHANGELOG, docs, full diff)
Next
Changelog