Release lifecycle

This page describes how the Arcantry project releases itself. It is not a required release process for projects that inspect or adopt Arcantry.

An Arcantry release is a dated set of archived OpenSpec changes. The internal release keeps repository state complete even when no package, Git tag, or GitHub Release is published.

The first public release retains 1.0.0 while neither its main npm package nor a public GitHub Release exists. After publication, the repository advances versions normally from the highest accepted OpenSpec impact. Updating master or GitHub Pages remains normal delivery, not a release.

release.md

Each Arcantry change carries its version impact and one or more release-facing consumer outcomes:

---
impact: minor
components:
  - repository-lifecycle
audiences:
  - developers
  - operators
observable_impact: user-felt
changelog: include
---

## Added

### Configure the farm layout

The farm layout is configurable without replacing the map wholesale.

## Fixed

### Preserve existing farm objects

Changing the layout no longer removes objects that remain valid in the selected layout.

Each level-two heading is one standard changelog category: Added, Changed, Fixed, Deprecated, Removed, or Security. Each level-three heading and its body describe one distinct consumer outcome, not an implementation summary. A category may contain several outcomes.

Existing release artifacts may retain the legacy category frontmatter with one level-one title and body. New artifacts use the categorized body shown above. One file cannot mix the two structures.

SemVer changes record patch, minor, or major impact. Integer and calendar projects can omit it. When a release is authorized, planning rejects an unassigned none change and uses the highest impact in the release set. Recording impact does not authorize a version change.

audiences contains project-defined slugs. observable_impact is customer-outcome, user-felt, significant-technical, or maintenance. changelog: include publishes the entry, while omit keeps the change in release state and SemVer calculation without publishing its prose. Historical release artifacts may retain visibility.

components lists one or more stable affected Arcantry surfaces, such as cli, catalog, docs, repository-adoption, or skill:<name>.

Multi-unit projects may add unit_impacts when the same change has a different SemVer effect in each matching unit. The scalar impact remains the fallback. A composed parent change may add dependency_updates to acknowledge newer direct dependencies. Impact, audiences, observable impact, inclusion, components, unit impacts and dependency updates remain shared by every outcome in the change.

Several changes can form one audience-facing story only through projection_group: <id> on every member and a matching release-groups/<id>.yaml file. The group owns its category, audiences, title, body and ordered member list. Rendering emits the prose once and retains an OpenSpec marker for every member.

Arcantry resolves each change’s schema from .openspec.yaml, with fallback to its OpenSpec source config.yaml. A schema whose release artifact generates release.md is release-bearing. A schema without that artifact is intentionally non-release and must not add release.md; it is skipped without using impact: none.

Manifest

An Arcantry release manifest contains only identity and grouping data:

version: 1.0.0
date: 2026-08-18
changes:
  - configurable-farm-layout
  - fix-save-corruption

Change ids must resolve to openspec/changes/archive/ and may belong to only one release.

That uniqueness rule belongs to the single-release shape. A multi-unit manifest identifies its unit and may pin direct dependencies:

format: 2
unit: app
version: 2.1.0
date: 2026-08-23
changes:
  - update-app-runtime
dependencies:
  core: 1.4.0

Multi-unit assignment is unique per (unit, change), so one shared outcome can reach several matching units at different versions or times.

Project release topologies

• single keeps one version, manifest stream and changelog. It is the default topology.
• independent gives every unit its own version, manifests and changelog. There is no generated root release or central changelog.
• composed adds an acyclic unit dependency graph. Parent manifests pin exact direct dependencies, but a child release does not create a parent release.

A composed parent plan reports newer child releases as pending. The parent adopts them only when a selected parent change lists the direct dependency in dependency_updates. The parent’s SemVer still comes only from its own effective release impacts. A parent changelog can be the product summary, but it contains only parent-selected outcomes and never copies child entries automatically.

Flow

release-cut creates the manifest from the computed plan. It does not ask commits what changed and is run only as part of an explicitly authorized release.

Normal arcantry release check validates persisted release consistency while allowing active and unassigned work. arcantry release check --sealed is the final gate: it also rejects active changes, unassigned archives, uncommitted work, and commits after the latest release manifest. Ordinary host checks do not require a release; run release checks when preparing one.

The commit that introduces or explicitly reseals an authorized release manifest is the Arcantry release seal. It must also contain the archived OpenSpec changes, aligned distribution versions, dependency pins and generated changelog. Later work on master contributes its declared impact to the next release plan but does not by itself authorize another release.

Changelog provenance

By default, Arcantry’s public release adapter renders Keep a Changelog 2.0 with its preamble, Unreleased, dated bracketed versions, and standard categories. It can compose archived meaning from one or several explicit OpenSpec paths in a monorepo. Existing release prose is never reconstructed from Git.

Every published outcome carries an invisible OpenSpec source marker:

<!-- openspec: configurable-farm-layout -->

This keeps every generated outcome traceable without adding noise for readers. Several markers may therefore identify the same change when it delivered several outcomes.

Git history

Commits remain Arcantry’s implementation audit trail. A change can contain exploratory commits, refactors, test fixes, and corrections without any of them becoming release notes. The archived OpenSpec change is the release unit.

Arcantry release validation uses Git only to prove that no repository work follows the newest release seal. It never derives release prose, category, impact, visibility, or components from a commit message or diff.

Projects using Arcantry can observe a changelog without OpenSpec. Only a changelog configured for Arcantry management must derive new release meaning from explicit OpenSpec authorities.

npm publication

The public package is arcantry. npm publication consumes an already sealed Arcantry release; it does not create or reinterpret one.

For releases after the first public version:

1. Complete the internal release flow and push the seal commit.
2. Create a protected v<version> tag that points exactly to that commit.
3. Let the Native release workflow verify the tag, manifest, package version, repository metadata and exact package archives.
4. Approve the protected npm environment after the native binaries, installers, npm archives and draft GitHub Release have passed their checks.
5. The workflow publishes platform packages before the main package through npm trusted publishing, then makes the GitHub Release public. It does not use a stored npm write token.

The first publication is a one-time bootstrap because npm requires a package to exist before it can trust a CI publisher. The same tagged workflow still builds and verifies the release:

1. Push the protected release tag and let .github/workflows/release.yml build all native targets, test both installers, create the five exact npm archives and open the draft GitHub Release.
2. Leave the protected npm job waiting for maintainer approval.
3. Download the retained release-v<version> artifact from that workflow run without rebuilding it locally.
4. As an authorized npm maintainer with 2FA, publish the four platform archives in the workflow’s declared order, then publish the main arcantry archive.
5. Configure the GitHub Actions trusted publisher for every package with repository MrMaxie/arcantry, workflow release.yml, environment npm, and publication permission. Verify each relationship with npm trust list <package>.
6. Approve the protected npm job. It rechecks each registry integrity, skips exact matches and stops on any mismatch before making the GitHub Release public.
7. Require 2FA and disallow token-based publication after all trusted publishers have been verified.

The manual bootstrap archives do not carry OIDC publication provenance. Trusted publishing becomes effective and verifiable when a later version is published by the workflow.

Projects can select integer or calendar versions and a MiniJinja changelog template. See Release conventions for compatible version sources and preserved history.

Pull requests and master run CI, documentation changes run Pages, and protected v<version> tags run the native release workflow. The tag workflow keeps the GitHub Release as a draft until the protected npm publication gate completes.