Skip to content

docs(release): v0.3.0 changelog fold, upgrade notes and release checklist (ITL-873) - #329

Merged
eywalker merged 19 commits into
mainfrom
eywalker/itl-873-cut-the-orcapod-python-v030-release
Nov 17, 2026
Merged

eywalker merged 19 commits into
mainfrom
eywalker/itl-873-cut-the-orcapod-python-v030-release

Conversation

@eywalker

@eywalker eywalker commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Refs ITL-873

Release PR for v0.3.0. Two commits are still to come, after review and the developer's approval: the dating commit, then the freeze as the LAST commit (see the end). Do not merge before them.

What the release contains (head refreshed 2026-11-17 against main 62899bd)

Every v0.3.0 pull request has merged into main (the last: #406 ITL-1154, #409 ITL-1160, #408 ITL-1162, #410 and #411 ITL-1169), and main is merged into this branch (merges only, no rebase or force-push).

  • CHANGELOG.md: the 90 changelog.d/ fragments are folded into ## [0.3.0] by uv run python scripts/assemble_changelog.py --version 0.3.0, which deleted them (changelog.d/ keeps only README.md). The heading stays ## [0.3.0] — unreleased until the dating commit.
    • Upgrade notes: #### Upgrading from 0.2.0 opens Breaking changes and migration. It is a grouped list of every change a 0.2.0 (or 0.1.4) user meets, each with what to do and its issue: stored data (nothing written by 0.2.0 or a development build of v0.3 is reused; side effects of a development build are delivered again), requirements, renamed or removed names, running a job, operators, function pods, sources and binding, values refused now, extension authors, documentation. Its draft (docs/dev/plans/2026-11-15-v0.3-upgrade-notes-draft.md) is deleted in the same commit.
    • Order fix (coordinator's decision, option A): the fold appends each category's text fragment by fragment, by issue number, so 85 bullets-only fragment blocks had landed under an earlier fragment's #### heading and read as part of it. Each is moved, text unchanged, directly under its category, before the first #### entry; in Breaking changes and migration: the upgrade notes, then the moved bullets under a new #### Other breaking changes, then the detailed entries. scripts/assemble_changelog.py is not changed here; fixing its order is a separate issue after the tag.
  • docs/dev/plans/2026-11-15-v0.3-release-checklist.md: the v0.3.0 instance of RELEASING.md: steps with who and status, the PRs that landed, the pre-push checklist, and the nauticalab fast-forward push and Release workflow as the developer's steps.
  • RELEASING.md: as on main, plus: release dates are UTC days, and the freeze runs with TZ=UTC (the script dates the release revision with the local clock); the per-release checklists are in docs/dev/plans/. docs/reference/golden-hashes.md shows the same TZ=UTC command.
  • README.md, docs/index.md: install text (0.3.0 is the first PyPI release since 0.1.4; tables written by 0.2.0 are not read; see Upgrading from 0.2.0). README links are absolute so they resolve on PyPI.

Checks

  • On 095aca3e: pytest tests/test_docs tests/test_changelog_fragments.py tests/test_design_issues.py tests/test_contexts: 190 passed; assemble_changelog.py --check: OK; generate_golden_hashes.py --check: golden values of semantic, schema, arrow, datagram, pipeline, torch match; ruff check and ruff format --check clean; basedpyright 0 errors (exit 0). No golden file and no source file is changed by this PR. CI runs the full suite.

  • The order fix moved lines and changed none. Run from a checkout of this branch: it folds the parent commit ac953e3b afresh, adds the upgrade notes' lines and the one new heading, and compares the sorted non-blank lines with the committed CHANGELOG.md:

    W=$(mktemp -d); git worktree add -q --detach "$W" ac953e3b
    (cd "$W" && uv run --quiet python scripts/assemble_changelog.py --version 0.3.0 >/dev/null)
    { grep -v '^$' "$W/CHANGELOG.md"
      sed -n '/<!-- BEGIN UPGRADE NOTES -->/,/<!-- END UPGRADE NOTES -->/p' \
        "$W/docs/dev/plans/2026-11-15-v0.3-upgrade-notes-draft.md" | sed '1d;$d' | grep -v '^$'
      echo '#### Other breaking changes'; } | sort > expected.txt
    git show 095aca3e:CHANGELOG.md | grep -v '^$' | sort > actual.txt
    diff expected.txt actual.txt && echo "same lines: only moved"
    git worktree remove --force "$W"

    It prints same lines: only moved. Every bullets-only block now sits directly under its own category (checked: 0 misplaced), and no heading lacks its blank lines.

  • Review: the CodeRabbit CLI loop is dropped for v0.3.0 (developer, 2026-11-16, budget). Earlier CLI records on this PR cover heads up to 3876a0e6. Coverage for the final head is the in-PR CodeRabbit review, CI and the coordinator's verification.

The one-off script that moved the blocks (not committed)
"""Move bullets-only fragment blocks of [0.3.0] above the category's #### entries.

Run after the fold and after the upgrade notes are inserted. Usage:
    reorder_changelog.py CHANGELOG.md FRAGMENTS_SNAPSHOT_DIR
Text is moved, never changed; the one added line is '#### Other breaking changes'.
"""
import sys
from pathlib import Path

sys.path.insert(0, "scripts")
import assemble_changelog as ac  # noqa: E402

BREAKING = "### Breaking changes and migration"
UPGRADE = "#### Upgrading from 0.2.0"
OTHER = "#### Other breaking changes"

changelog, snap = Path(sys.argv[1]), Path(sys.argv[2])
lines = changelog.read_text(encoding="utf-8").split("\n")
frags, problems = ac.load_fragments(snap)
assert not problems, problems
start, end = ac._section_bounds(lines, "0.3.0")
section = lines[start:end]

# Split the section into categories.
cats: list[tuple[str | None, list[str]]] = [(None, [])]
for line in section:
    if line.startswith("### "):
        cats.append((line, [line]))
    else:
        cats[-1][1].append(line)


def find(seq: list[str], block: list[str], frm: int) -> int:
    for i in range(frm, len(seq) - len(block) + 1):
        if seq[i : i + len(block)] == block:
            return i
    return -1


moved_report = []
out_section: list[str] = []
for head, body in cats:
    if head is None:
        out_section += body
        continue
    blocks = [
        (p.name, c[head]) for p, c in frags if head in c
    ]
    first_h = next((i for i, l in enumerate(body) if l.startswith("#### ")), None)
    if first_h is None:
        out_section += body
        continue
    moved: list[list[str]] = []
    for name, block in blocks:
        if not ac._BULLET.match(block[0]) or any(l.startswith("#### ") for l in block):
            continue
        at = find(body, block, first_h)
        if at < 0:
            if find(body, block, 0) < 0:
                raise SystemExit(f"{name}: block not found in {head}")
            continue  # already above the first ####
        del body[at : at + len(block)]
        # remove a blank line left doubled where the block was
        if at < len(body) and at > 0 and body[at] == "" and body[at - 1] == "":
            del body[at]
        moved.append(block)
        moved_report.append(f"{head[4:]}: {name}")
    if not moved:
        out_section += body
        continue
    run = [l for b in moved for l in b]
    if head == BREAKING:
        assert body[first_h] == UPGRADE, body[first_h]
        nxt = next(i for i in range(first_h + 1, len(body)) if body[i].startswith("#### "))
        body[nxt:nxt] = [OTHER, ""] + run + [""]
    else:
        # append to the leading bullet run, or start one, before the first ####
        ins = first_h
        while ins > 0 and body[ins - 1] == "":
            ins -= 1
        leading_bullets = any(ac._BULLET.match(l) for l in body[1:ins])
        body[ins:ins] = run if leading_bullets else [""] + run
    out_section += body

lines[start:end] = out_section
changelog.write_text("\n".join(lines), encoding="utf-8")
print(f"moved {len(moved_report)} block(s)")
for r in moved_report:
    print("  " + r)

It ran after the fold and after the upgrade notes were inserted, with a copy of changelog.d/ taken before the fold as FRAGMENTS_SNAPSHOT_DIR.

The remaining two commits (on the coordinator's go, after the developer's approval)

  1. Dating commit: the heading becomes ## [0.3.0] — YYYY-MM-DD, the UTC day the developer tags (expected 2026-11-17).
  2. Freeze, the LAST commit: TZ=UTC uv run python tests/test_hashing/golden/generate_golden_hashes.py --release 0.3.0. It appends the release revision to the golden history of src/orcapod/contexts/data/v1.json and pins it in src/orcapod/contexts/released_manifests.json (v1's first release: also released_in and the manifest pin). Before committing, its recorded date is checked against the heading. The Release workflow refuses a release without it. After it, a released golden value never changes; any change needs a new data context. If anything lands on main afterwards, or the tag moves to another UTC day, the freeze is dropped and run again.

No version bump, tag, Release workflow run, push to nauticalab or setting change is part of this PR.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added comprehensive unreleased 0.3.0 upgrade guidance covering breaking changes, behavior updates, fixes, and known limitations.
    • Updated installation and README guidance to clarify release availability and compatibility with data written by earlier versions.
    • Linked to hosted documentation and Getting Started resources.
  • Chores
    • Standardized release-date guidance around UTC and updated release checklists and golden-hash instructions.

…(ITL-873)

Assemble the changelog fragments into [0.3.0], add the SemiJoin fragment (ITL-847),
add the upgrade notes, the v0.3 release checklist and the data context freeze step.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

Walkthrough

This pull request prepares v0.3.0 release documentation. It consolidates upgrade guidance and release notes in the changelog, removes individual changelog fragments, adds a release checklist, updates release-date instructions, and revises installation and documentation links.

Changes: v0.3.0 Release Documentation

Layer / File(s) Summary
Consolidated changelog and fragment removal
CHANGELOG.md, changelog.d/*
The changelog adds v0.3.0 upgrade guidance, breaking changes, additions, behavior notes, fixes, and known limitations. Individual changelog fragments are removed; these removals do not establish implementation changes.
Release procedure and checklist
RELEASING.md, docs/dev/plans/2026-11-15-v0.3-release-checklist.md, docs/reference/golden-hashes.md
Release instructions run golden-history generation in UTC and align the recorded release date with the changelog heading. The new checklist records release steps, checks, and evidence.
Release and upgrade information
README.md, docs/index.md
The pages describe the 0.3.0 release history and table compatibility, link to upgrade guidance, and point to hosted documentation pages.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Possibly related PRs

  • metamorphic-labs/orcapod-python#269: Prepares the v0.2.0 changelog, release documentation, and checklist, which are similar to the v0.3.0 release materials in this pull request.
  • metamorphic-labs/orcapod-python#271: Adds documentation-sample tests and edits README and documentation content; this pull request also changes those documentation surfaces and reports documentation test validation.
Merge Risk: Moderate · up to 095ac

This PR only changes release documentation. The v0.3.0 changelog still contains entries that conflict with later ones, including a repeat-delivery instruction that delivers nothing and an outdated hash recipe. Users upgrading from 0.2.0 or 0.1.4 could follow the wrong instructions, so correct these entries before the release is cut.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

LanguageTool

CHANGELOG.md

LanguageTool checks are incomplete because the per-file request limit of 5 was reached. Remaining text was skipped; findings from completed checks are retained.

@linear-code

linear-code Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
ITL-873 Cut the Orcapod Python v0.3.0 release

Overview

Final step of the v0.3 release project. Once every issue committed to milestones 1 to 3 is merged or explicitly moved out, prepare the release notes and mark the release commit with the tag v0.3.0. v0.3 is a minor version because it adds features.

Goals & Success Criteria

  • Changelog and upgrade notes cover every behaviour change in v0.3, including any change that affects stored tables, following the policy decided in ITL-853.
  • The version resolves to 0.3.0 from the tag.
  • Required CI is green on the tagged commit of main.
  • The hash and type probe shows no unintended change against v0.2.0; every intended change is listed in the release notes.
  • The tag v0.3.0 is pushed. Publishing to the internal registry follows the release runbook, if the registry exists by then.

Scope & Boundaries

In scope:

  • Release notes, version check, tag, and publishing per the runbook.

Out of scope:

  • Any feature or fix work; those belong to milestones 1 to 3.

Dependencies & Risks

  • Depends on all issues in milestones 1 to 3 of this project.
  • Publishing depends on the internal registry being available.

Review in Linear

Edgar Y. Walker and others added 2 commits November 15, 2026 00:33
Restore CHANGELOG.md and changelog.d/ to main's state (the earlier fold
was stale). Keep the install text in README.md and docs/index.md and the
freeze step in RELEASING.md, reconciled with main. Replace the
2026-11-12 checklist with a 2026-11-15 one and add the upgrade notes
draft, to be inserted at the fold.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s (ITL-873)

Side-effect deliveries repeat after clear_cache(), not through a
job.run() argument. Add a note for users coming from 0.1.4 and link the
README to the section's anchor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review, run 1 — coderabbit review --agent --base origin/main on head c93472a7 (base origin/main 2659b41). Completed, 5 files reviewed, 2 findings.

# Severity File Finding Action
1 major superpowers/plans/2026-11-15-v0.3-upgrade-notes-draft.md The note told users to call job.run(track_completion=False), but PipelineJob.run() has no such parameter. Fixed in 26bc740d. track_completion is a side-effect pod setting. The note now says to deliver through job.run() and, to repeat deliveries, to call clear_cache() on the node first (ITL-1091, ITL-1095).
2 minor README.md The link to Upgrading from 0.2.0 has no anchor, and nothing tells users coming from 0.1.4 what to do. Fixed in 26bc740d. Added a Coming from 0.1.4 paragraph based on ITL-944: the 0.2.0 migration commands are removed, and a 0.1.4 table is reported but never read. The README link now points to CHANGELOG.md#upgrading-from-020, which becomes a real heading at the fold.

Run 2 is on 26bc740d.

Posted by a Claude Code agent on behalf of @eywalker.

…th bindings.store (ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review, run 2 — coderabbit review --agent --base origin/main on head 26bc740d. Completed, 5 files reviewed, 2 new findings, both in the upgrade notes draft.

# Severity Finding Action
1 minor "is never modified" conflicts with "into new tables" when v0.3 is given the same database. Fixed in 5bb446d6. The old tables are never modified; given the same database, v0.3 writes new tables beside them at new paths (ITL-944, ITL-945).
2 minor A 0.2.0 job file does not load as-is: it names its database under bindings.store, and loading it raises ValueError (ITL-1082). Fixed in 5bb446d6; confirmed that v0.2.0 job.py writes bindings.store. The bullet now gives the fix (load(path, database=...) or rename the key) and then what a loaded file shows.

Run 3 is on 5bb446d6.

Posted by a Claude Code agent on behalf of @eywalker.

@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review, run 3: coderabbit review --agent --base origin/main on head 5bb446d6. It completed and reviewed 5 files with 0 findings, so the CLI review loop is done on this head.

This head does not include the data context freeze commit. It is held locally for the developer's approval and will be reviewed when it is added.

Posted by a Claude Code agent on behalf of @eywalker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Edgar Y. Walker and others added 2 commits November 15, 2026 13:04
…order (ITL-873)

Upgrade notes: ITL-1147, ITL-611 set container, ITL-1150, PLT-4864 and an
ITL-946 placeholder. Checklist: fragment PRs done; remaining order ITL-946,
fold, freeze as the last commit, tag; v* tag protection precondition.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…TL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review (coderabbit review --agent --base origin/main) of 718565ef (merge of main d813d7fe, upgrade notes and checklist refresh). Completed, 5 files reviewed, no review_failed.

Finding Action
minor, README.md:23: the README is the PyPI long description, so the relative CHANGELOG.md link is broken on PyPI Fixed in 3a5148d0: the link, and the two relative docs/ links at the top of the README (same defect, already on main), point to https://github.com/nauticalab/orcapod-python/blob/main/..., keeping the #upgrading-from-020 anchor

A new run on the fixed head follows.

Posted by a Claude Code agent on behalf of @eywalker.

@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review (coderabbit review --agent --base origin/main) of 3a5148d0 (README absolute links). Completed, 5 files reviewed, no review_failed.

Finding Action
minor, README.md:23: CHANGELOG.md has no Upgrading from 0.2.0 heading, so #upgrading-from-020 does not resolve Declined, by design: the release PR's fold (phase B) inserts #### Upgrading from 0.2.0 (drafted in superpowers/plans/2026-11-15-v0.3-upgrade-notes-draft.md) at the head of Breaking changes and migration of ## [0.3.0], so the anchor resolves in the released CHANGELOG.md. The link must not point to the 0.2.0 section, which is not the 0.3 upgrade path. To be re-checked on the folded head.

No code change, so no new head; the next CLI run is on the phase B head.

Posted by a Claude Code agent on behalf of @eywalker.

Edgar Y. Walker and others added 3 commits November 15, 2026 13:53
…ories (ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ITL-873)

RELEASING.md takes main's golden-history release step in place of the
branch's old freeze step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… ITL-1154 before the fold (ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review (coderabbit review --agent --base origin/main) of e4ad3f27 (merge of main 4dd015a4 with #399/ITL-946, RELEASING.md conflict resolved to main's release step; ITL-946 upgrade note from its fragment; checklist adds ITL-1154 before the fold and the --release 0.3.0 freeze the Release workflow now requires). Completed, 5 files reviewed, no review_failed.

No findings. The earlier declined finding (#upgrading-from-020 anchor, resolved by the fold) did not recur.

Posted by a Claude Code agent on behalf of @eywalker.

Edgar Y. Walker and others added 2 commits November 16, 2026 01:49
…(ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker

Copy link
Copy Markdown
Contributor Author

CodeRabbit CLI review (coderabbit review --agent --base origin/main) of 3876a0e6 (merge of main 3d859d2d with #400/ITL-1159, no conflict; ITL-1159 upgrade note; checklist rows). Completed, 5 files reviewed, no review_failed.

No findings.

Posted by a Claude Code agent on behalf of @eywalker.

Edgar Y. Walker and others added 3 commits November 16, 2026 16:44
….3.0 release branch (ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-873)

Lines from the fragments merged today: the v1 hash definition (development
builds discarded, side effects delivered again, source id forms,
record_id_columns, text record ids), map_tags / map_data strictness and
keyword-only options, and connector databases refusing function nodes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…C (ITL-873)

generate_golden_hashes.py --release dates the release revision with the
local clock, so RELEASING.md and the golden-hashes reference run it with
TZ=UTC and check the date against the CHANGELOG heading. The checklist
records today's merges, the fold reorder (option A) and the dating commit
before the freeze.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Edgar Y. Walker and others added 4 commits November 16, 2026 17:55
… branch (ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t to docs/dev/plans (ITL-873)

Development documents live under docs/dev/ (ITL-1169). The checklist
records the merge of main e38d3a2 (#410).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he v0.3.0 release branch (ITL-873)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	RELEASING.md
assemble_changelog.py --version 0.3.0 folds the 90 fragments into
[0.3.0] and deletes them. The upgrade notes (#### Upgrading from 0.2.0)
open Breaking changes and migration; their draft is deleted. Each
bullets-only fragment block that had landed under an earlier fragment's
#### heading is moved, text unchanged, directly under its category
(Breaking: under a new #### Other breaking changes). The heading stays
'unreleased' until the dating commit before the freeze.

RELEASING.md names docs/dev/plans/ for the release checklists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker eywalker changed the title docs(release): prepare v0.3.0 changelog, upgrade notes and checklist (ITL-873) docs(release): v0.3.0 changelog fold, upgrade notes and release checklist (ITL-873) Nov 17, 2026
@eywalker
eywalker marked this pull request as ready for review November 17, 2026 02:48
@eywalker
eywalker merged commit d92e8b8 into main Nov 17, 2026
19 of 20 checks passed
eywalker added a commit that referenced this pull request Nov 17, 2026
…ry (ITL-873) (#413)

* docs(release): date the v0.3.0 changelog heading 2026-11-17 (ITL-873)

The release date is the UTC day of the tag. #329 merged with the fold but
without its last two commits; this follow-up PR carries them, the freeze
last. The checklist records it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(release): record v0.3.0 in the golden history of data context v1 (ITL-873)

TZ=UTC uv run python tests/test_hashing/golden/generate_golden_hashes.py --release 0.3.0

Appends the release revision (release 0.3.0, date 2026-11-17, added {})
to the golden history of std:v1:default, sets released_in, and pins the
revision digest and the manifest digest in released_manifests.json. No
golden file changes. From now on a released golden value changes only
with a new data context version.

Approved by the developer on 2026-11-17.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Edgar Y. Walker <>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
eywalker pushed a commit that referenced this pull request Nov 17, 2026
…al tags slice (ITL-1023)

Clean merge: README rewrite (#412), changelog fold (#329), v0.3.0 date and
golden release record (#413). Data context v1 is frozen as release 0.3.0;
the golden folder and src/orcapod/contexts are byte-identical to main. The
slice's changelog fragments (ITL-1017, ITL-1019, ITL-1022, ITL-1023) stay
fragments for the next release.

Refs ITL-1023

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eywalker
eywalker deleted the eywalker/itl-873-cut-the-orcapod-python-v030-release branch November 17, 2026 07:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant