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.

This repository currently uses continuous 1.0 delivery. Product and distributable versions stay at 1.0.0 until a maintainer explicitly authorizes a version change. Updating master or GitHub Pages is normal delivery, not a release.

release.md

Each Arcantry change carries its release-facing outcome and version impact:

---
category: changed
impact: minor
visibility: public
components:
  - repository-lifecycle
---

# Configurable farm layout

The farm layout is configurable without replacing the map wholesale.

The body describes the delivered outcome, not an implementation summary.

category is added, changed, fixed, deprecated, removed, or security.

Completed changes record patch, minor, or major impact. 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.

visibility: public publishes the entry in CHANGELOG.md. internal keeps the change in release state without publishing its prose.

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

Projects using openspec-release@2 may add unit_impacts when the same outcome has a different SemVer effect in each matching unit. The scalar impact remains the fallback. A composed parent outcome may add dependency_updates to acknowledge newer direct dependencies. The title, body, category and visibility remain shared: materially different consumer stories belong in separate OpenSpec changes.

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 v1 single-release adapter. A v2 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

V2 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 for v2 and the only v1 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 release check validates persisted release consistency while allowing active and unassigned work. release check --sealed is the final gate: it also rejects active changes, unassigned archives, uncommitted work, and commits after the latest release manifest. just check runs the normal consistency check automatically.

The commit that introduces an authorized release manifest is the Arcantry release seal. It must also contain the archived OpenSpec changes, aligned distribution versions, and generated changelog. Later work on master continues under the unchanged 1.0.0 policy and does not by itself authorize another release.

Changelog provenance

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.

Published entries carry an invisible OpenSpec source marker:

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

This keeps generated output traceable without adding noise for readers.

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 normal releases:

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 Publish npm workflow verify the tag, manifest, package version, repository metadata and exact package archive.
4. The workflow publishes through npm trusted publishing from the protected npm GitHub environment. 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:

1. Build and verify the release archive from the exact seal commit.
2. As an authorized npm maintainer with 2FA, run npm publish <archive>.
3. Assign organization governance for the unscoped package when required.
4. In the package settings on npmjs.com, add the GitHub Actions trusted publisher for repository MrMaxie/arcantry, workflow release.yml, environment npm, and the npm publish action.
5. Require 2FA and disallow token-based publication after the trusted publisher has been verified.

Do not create the first version tag before bootstrap is complete. Automated tag publication starts with the next sealed version.