# Releasing & versions

Source: https://docs.externa.qiick.io/docs/releasing

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

> **Related**
> [Changelog (docs)](/docs/changelog) · [`CHANGELOG.md`](https://github.com/qiick-io/externa-core/blob/develop/CHANGELOG.md) · [`.github/RELEASE_TEMPLATE.md`](https://github.com/qiick-io/externa-core/blob/develop/.github/RELEASE_TEMPLATE.md) · [API 1.x compatibility](/docs/api-compatibility) · [Contributing](/docs/contributing) · [Packagist & create-project](/docs/packagist)

## Version source of truth

| File                        | Role                                     |
| --------------------------- | ---------------------------------------- |
| `composer.json` → `version` | Canonical package version                |
| `package.json` → `version`  | Must match Composer                      |
| README badge / version line | Update when bumping                      |
| Docs site                   | No 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](/docs/api-compatibility):

| Bump                                 | When                                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Major**                            | Breaking Public API / GraphQL / documented operator contracts after deprecation (or security-driven breaks called out in notes) |
| **Minor**                            | Additive features; deprecations may be announced                                                                                |
| **Patch**                            | Bug 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](https://keepachangelog.com/) 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](https://packagist.org/packages/qiick/externa-core) ([submit runbook](/docs/packagist#maintainer-submit-to-packagist-manual)) · docs deploy as usual

**Shipped:** [externa-core `v1.0.0-beta.4`](https://github.com/qiick-io/externa-core/releases/tag/v1.0.0-beta.4) (2026-09-17) on Packagist. **GA:** [externa-core `v1.0.0`](https://github.com/qiick-io/externa-core/releases/tag/v1.0.0) — human merges the release PR, tags, and confirms Packagist. Docs site for this cut: **`1.1.1`**. See [Packagist status](/docs/packagist#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)