julia-release

Files (1)

• SKILL.md

SKILL.md (first lines)

# Releasing a Julia package

**One path, for every release — breaking or not.** Commit the version bump yourself, push it,
then comment on that commit calling `@JuliaRegistrator` with the release notes in the same
comment.

Do **not** dispatch `.github/workflows/Register.yml`. Why not is at the bottom; it is not a
fallback for patch releases either.

**Contents**

- [The procedure](#the-procedure)
  1. [Close out the CHANGELOG](#1-close-out-the-changelog)
  2. [Set the version](#2-set-the-version)
  3. [Commit both together](#3-commit-both-together)
  4. [Push, and wait properly](#4-push-and-wait-properly)
  5. [Comment on the release commit](#5-comment-on-the-release-commit)
  6. [Watch the registry PR, then TagBot](#6-watch-the-registry-pr-then-tagbot)
- [Why the notes must be in that first comment](#why-the-notes-must-be-in-that-first-comment)
- [Why not `Register.yml`](#why-not-registeryml)
- [The General-registry rebase trap](#the-general-registry-rebase-trap)
- [Checking whether registration landed](#checking-whether-registration-landed)
- [Report](#report)

## The procedure

### 1. Close out the CHANGELOG

Feature PRs do not bump the version — their entries accumulate under
`## [Unreleased] — targeting X.Y.Z`. The close-out turns that heading into the released version.
What is known-broken is in the repository's `KNOWN_ISSUES.md`, not in the changelog.

Read the section's headline paragraphs against `Project.toml`'s `[compat]` floors and against the
section's own entries. No branch rewrites the headline, so it is where a stale claim survives.

The notes you write here are the notes that go in the Registrator comment and, via TagBot, into
the GitHub release. Write them once, properly.

### 2. Set the version

Edit `version = "X.Y.Z"` in `Project.toml` by hand. Any `0.x` **minor** bump is breaking.

### 3. Commit both together

`CHANGELOG.md` and `Project.toml` in **one commit** — that commit is the release, and its SHA is
what Registrator will be pointed at.

```
Release X.Y.Z
```

### 4. Push, and wait properly

`git push` runs the full suite through `.githooks/pre-push`: 10–30 minutes with no output.
Background it, watch the remote ref, do not kill it:

```bash
git ls-remote origin refs/heads/<branch>
```

Not `gh api`: `gh` only escapes the sandbox when every part of the command is excluded, so it
fails inside a loop, in `$( )`, after a `cd … &&` or before a pipe. A `git` inside a loop is
sandboxed too. It verifies against a CA file and reads a public remote, but it errors where the
remote needs credentials. Treat an error from a poll as UNKNOWN, never as "not pushed".

### 5. Comment on the release commit

**Every registration comment carries release notes**, and a breaking one carries a
breaking-changes section. Build the body rather than typing it:

```bash
julia --startup-file=no ~/Research/Harness/githooks/release-notes.jl <package-dir> > notes.json
gh api repos/<owner>/<repo>/commits/<SHA>/comments --input notes.json
```

Run `wc -c notes.json` before you post it. Registrator accepts about 3 kB and fails a 137 kB
comment with "An unexpected error occurred during registration" while GitHub takes the comment.
For a large section, write the body by hand in the shape below, and encode it with
`jq -Rs '{body: .}' notes.md > notes.json`. Shrink the notes, never the CHANGELOG section. `gh` runs
outside the sandbox, where `$TMPDIR` differs, so pass it the file by absolute path.

It reads the version from `Project.toml`, lifts that version's `CHANGELOG.md` section, and
**exits 1 with empty stdout** — no `notes.json` — if the release is breaking and the section has
no breaking-changes heading, or if the close-out was never done. Breaking here means what
Registrator labels `BREAKING`: any `0.0.z`, a `0.y.0` minor bump, an `x.0.0` major bump, or a
bump that skipped the `.0` because a version number was burned.

What it emits, and what to write by hand if the script is unavailable:

```
@JuliaRegistrator register

Release notes:

## Breaking Changes

- <what broke, and what a caller should do about it>

## New Features
...
```

The section names are the CHANGELOG's own, promoted one level — the notes *are* the section
just closed out, not a second thing written for the occasion.

**Never `-F body=@file`** — it mangles multi-line bodies. That, and forgetting the notes, are
the two reasons the body is assembled by script.

Release notes go in **from the start**. They are not something to add after AutoMerge
complains, because by then the registry PR body is already written.

### 6. Watch the registry PR, then TagBot

AutoMerge, then TagBot cutting the GitHub release. A release is not done when the registry PR
opens.

AutoMerge waits about 3 days only for the first registration of a new package. A new version of a
registered package, breaking or not, merges about 15 minutes after its checks pass. A breaking
version without the release-notes block is blocked, not delayed.

From michakraus/ResearchHarness, MIT.

More from michakraus/ResearchHarness