Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .zed/rules
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,25 @@ Examples:
- test(function_pod): add schema validation tests
- refactor(schema_utils): use Schema.optional_fields directly

## Changelog

A pull request never edits CHANGELOG.md (developer, November 11, 2026; ITL-961). It adds
exactly one file, changelog.d/<ISSUE-ID>.md (e.g. changelog.d/ITL-955.md; a PR that
resolves several issues uses its primary issue's id).

- The file holds only the text that would have gone under the release heading in
CHANGELOG.md: the same category headings CHANGELOG.md uses
(### Breaking changes and migration, ### Added, ### Changed, ### Fixed,
### Known limitations), each followed by its bullet lines; no version heading, no date.
- If your branch already edits CHANGELOG.md, restore CHANGELOG.md to its state on the
branch's base and move that text, unchanged, into the fragment.
- Check a fragment with uv run python scripts/assemble_changelog.py --check
(tests/test_changelog_fragments.py runs it in CI).
- Only the release PR changes CHANGELOG.md: it folds the fragments in with
uv run python scripts/assemble_changelog.py --version X.Y.Z, which also deletes them
(see RELEASING.md). Entries already in CHANGELOG.md on main stay there.
- changelog.d/README.md is the full statement of the convention.

## Lint, format and type checks

Every pull request must pass the metamorphic-labs required CI, which runs exactly these
Expand Down
19 changes: 19 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,25 @@ Examples:
- `test(function_pod): add schema validation tests`
- `refactor(schema_utils): use Schema.optional_fields directly`

## Changelog

A pull request never edits `CHANGELOG.md` (developer, November 11, 2026; ITL-961). It adds
exactly one file, `changelog.d/<ISSUE-ID>.md` (e.g. `changelog.d/ITL-955.md`; a PR that
resolves several issues uses its primary issue's id).

- The file holds only the text that would have gone under the release heading in
`CHANGELOG.md`: the same category headings `CHANGELOG.md` uses
(`### Breaking changes and migration`, `### Added`, `### Changed`, `### Fixed`,
`### Known limitations`), each followed by its bullet lines; no version heading, no date.
- If your branch already edits `CHANGELOG.md`, restore `CHANGELOG.md` to its state on the
branch's base and move that text, unchanged, into the fragment.
- Check a fragment with `uv run python scripts/assemble_changelog.py --check`
(`tests/test_changelog_fragments.py` runs it in CI).
- Only the release PR changes `CHANGELOG.md`: it folds the fragments in with
`uv run python scripts/assemble_changelog.py --version X.Y.Z`, which also deletes them
(see `RELEASING.md`). Entries already in `CHANGELOG.md` on `main` stay there.
- `changelog.d/README.md` is the full statement of the convention.

## Lint, format and type checks

Every pull request must pass the metamorphic-labs required CI, which runs exactly these
Expand Down
23 changes: 20 additions & 3 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,26 @@ requires, on each index, a trusted publisher for the `orcapod` project naming ow

Do these on `main` before triggering the workflow:

1. **Update `CHANGELOG.md`** — rename the top section to the version being released, set
its date, and make sure breaking changes carry migration notes. The GitHub Release
body is generated from PR titles; `CHANGELOG.md` is the curated record.
1. **Update `CHANGELOG.md`** in a release pull request, the only kind of pull request that
edits it. Feature pull requests add `changelog.d/<ISSUE-ID>.md` fragments instead (see
`changelog.d/README.md`).
1. Fold the fragments into the section of the version being released:

```
uv run python scripts/assemble_changelog.py --version X.Y.Z
```

This appends each fragment's text to the matching category of `## [X.Y.Z]` (in order
of issue id, without moving the lines already there), creates the section or a
category if it is missing, and deletes the fragments. It stops without changing
anything if a fragment is malformed; `--check` reports the same problems without
folding. Commit the changed `CHANGELOG.md` and the deleted fragments together;
`changelog.d/README.md` stays.
2. Set the section's heading to the version being released and its date
(`## [X.Y.Z] — YYYY-MM-DD`), and make sure breaking changes carry migration notes.

The GitHub Release body is generated from PR titles; `CHANGELOG.md` is the curated
record.
2. **Check that `main` is green** — the `Run Tests` workflow on the commit you are
releasing. The Release workflow re-runs the unit tests on Python 3.11, 3.12 and 3.13
and the license check, but not the PostgreSQL or SpiralDB integration jobs.
Expand Down
69 changes: 69 additions & 0 deletions changelog.d/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Changelog fragments

A pull request never edits `CHANGELOG.md` (developer, November 11, 2026; ITL-961). It adds
exactly one file here instead, so two open pull requests never conflict on the changelog.

## The rule

- The file is `changelog.d/<ISSUE-ID>.md`, for example `changelog.d/ITL-955.md`. A pull
request that resolves several issues uses its primary issue's id.
- The file holds only the text that would have gone under the release heading in
`CHANGELOG.md`: the same category headings `CHANGELOG.md` uses, each followed by its
bullet lines. No version heading, no date.
- If your branch already edits `CHANGELOG.md`, restore `CHANGELOG.md` to its state on the
branch's base and move that text, unchanged, into the fragment.
- A change with nothing to tell users (tests, internal tooling) adds no fragment.

The category headings, in the order they appear in a release section:

```markdown
### Breaking changes and migration
### Added
### Changed
### Fixed
### Known limitations
```

Use only the ones you need. Under a heading, write what `CHANGELOG.md` has today: bullet
lines, or a `####` sub-heading followed by paragraphs for a change that needs explaining.

## Example

`changelog.d/ITL-955.md`:

```markdown
### Added

- **`orcapod.errors.StoreError`** — the base of `StoreReadError` and `StoreWriteError`.
(ITL-955 #301)

### Fixed

- `Join` no longer raises on an empty right-hand stream. (ITL-955 #301)
```

## Checking a fragment

```
uv run python scripts/assemble_changelog.py --check
```

fails if a file in this directory other than `README.md` is not named `<ISSUE-ID>.md`, is
empty, has text before its first category heading, has a heading that is not one of the
categories above (`####` and deeper are fine), repeats a category, leaves a category empty,
or has a code fence that is never closed. `tests/test_changelog_fragments.py` runs the same
check, so CI rejects a malformed fragment.

## At release

The release pull request folds the fragments into `CHANGELOG.md` and deletes them (see
`RELEASING.md`):

```
uv run python scripts/assemble_changelog.py --version 0.3.0
```

Each category's text is appended to the same category of the `## [0.3.0]` section, in order
of issue id (team key, then issue number). Lines already in `CHANGELOG.md` are not moved or
changed: entries that were in `CHANGELOG.md` on `main` before this convention stay there.
This file stays; only the fragments are deleted.
Loading
Loading