docs: adopt scriv changelogs across the ecosystem (ADR 0009)

CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+Notable changes to the purescript-lua package set are recorded here. Each entry
+is a `psc-*` set release: the combination of fork versions consumers pin through
+`workspace.packageSet.url`. The format is based on
+[Keep a Changelog][keepachangelog], and entries are assembled from fragments in
+`changelog.d/` with [scriv][scriv] on each release ([ADR 0009][adr0009]).
+
+`scriv` for this repository comes from the pslua dev shell
+(`nix develop github:purescript-lua/purescript-lua`), since the set has no flake
+of its own.
+
+<!-- scriv-insert-here -->
+
+## psc-0.15.15-20260624 - 2026-06-24
+
+### Changed
+
+- The set is published as a single consumable `packages.json` for the new spago:
+  a RemotePackageSet (registry baseline with the Lua forks overlaid as git
+  entries) that consumers point `workspace.packageSet.url` at. `src/packages.json`
+  is now the source of truth ([ADR 0008][adr0008]).
+
+### Removed
+
+- The legacy `packages.dhall` release asset and the Dhall `upstream // lua` merge
+  model. spago 0.21 / Dhall is no longer supported.
+
+## psc-0.15.15-20260615-2 - 2026-06-15
+
+### Fixed
+
+- enums v6.1.2: `toCharCode` is length-guarded so a lone code-unit byte no longer
+  crashes (#102).
+
+## psc-0.15.15-20260615 - 2026-06-15
+
+### Fixed
+
+- The bulk of the FFI campaign landed here: console v6.1.1 (`error`/`warn` to
+  stderr, #76 #77), numbers v9.1.2 and v9.1.3 (the `Number` formatting contract,
+  #92–#98), integers v6.1.2 (32-bit `Int` semantics, #85–#91), enums v6.1.1
+  (UTF-8 `Char` code points, #79 #80), effect v4.1.3 (`forE` half-open range,
+  #78), exceptions v6.1.1 (Lua 5.1 `Effect.Exception`, #81–#84), arrays v7.4.0 and
+  v7.4.1 (5.1-safe `table.pack`/`unpack`/`move`), st v6.4.0 (`ST.for` half-open
+  range), prelude v7.3.0, and safe-coerce v2.0.1.
+
+## psc-0.15.15-20260614-4 - 2026-06-14
+
+### Fixed
+
+- effect v4.1.2 and assert v6.1.1: luacheck-clean FFI.
+
+## psc-0.15.15-20260614-3 - 2026-06-14
+
+### Fixed
+
+- control v6.0.1 (`arrayExtend` for Lua 5.1) and foldable-traversable v6.1.1
+  (1-based `mapWithIndex`).
+
+## psc-0.15.15-20260614-2 - 2026-06-14
+
+### Fixed
+
+- effect v4.1.1, integers v6.1.1, and numbers v9.1.1: the first batch of FFI
+  bugfixes.
+
+## psc-0.15.15-20260614 - 2026-06-14
+
+### Fixed
+
+- prelude v7.2.2: `Array` `Semigroup` append (`concatArray`).
+
+## psc-0.15.15-20260613-2 - 2026-06-13
+
+### Added
+
+- strings v6.2.0: `Data.String.CodePoints` implemented for UTF-8.
+
+## psc-0.15.15-20260613 - 2026-06-13
+
+### Fixed
+
+- prelude v7.2.1: Lua 5.1 FFI compatibility.
+
+## psc-0.15.15-20260612 - 2026-06-12
+
+### Fixed
+
+- prelude v7.2.0 restored, bringing back `unit = {}` so `Array Unit` no longer
+  collapses to an empty table ([ADR 0004][adr0004]).
+
+## Earlier
+
+Set releases before the 2026 FFI campaign (the `psc-0.15.8-*` and
+`psc-0.15.15-2024*` series, 2023–2024) tracked upstream package-set updates and
+the initial Lua forks. They predate this changelog and are recorded only as
+`psc-*` tags.
+
+<!-- scriv-end-here -->
+
+[keepachangelog]: https://keepachangelog.com/en/1.1.0/
+[scriv]: https://scriv.readthedocs.io/
+[adr0004]: docs/adr/0004-unit-is-empty-table.md
+[adr0008]: docs/adr/0008-new-spago-and-json-package-set.md
+[adr0009]: docs/adr/0009-changelogs-via-scriv.md

CONTRIBUTING.md

@@ -41,12 +41,29 @@ All forks share one workflow: substituters pinned in `extra_nix_config` (no
 Each fork has an `AGENTS.md` (the single source) and a one-line `CLAUDE.md` that
 imports it with `@AGENTS.md`. Edit `AGENTS.md`; never duplicate.
 
-## Releasing ([ADR 0006](docs/adr/0006-fork-release-by-annotated-tag.md))
-
-Annotated git tag on `master` → bump the fork's version in `src/packages.json` →
-regenerate the README package table (`scripts/gen-readme-table.sh`) →
-refresh `latest-compatible-sets.json` → push a `psc-*` set tag. A tooling-only PR
-needs no release.
+## Changelogs ([ADR 0009](docs/adr/0009-changelogs-via-scriv.md))
+
+Every repository keeps a `CHANGELOG.md` managed with
+[scriv](https://scriv.readthedocs.io/): fragments in `changelog.d/`, assembled
+into a dated section by `scriv collect` on release. Forks provide `scriv` in
+their `flake.nix` dev shell; this set repository has no flake, so its `scriv`
+comes from the pslua dev shell (`nix develop github:purescript-lua/purescript-lua`).
+
+- A change that touches `src/` adds a fragment: `scriv create` writes a template
+  under `changelog.d/`; fill in the right category (Added/Changed/Fixed/Removed)
+  and commit it with the change. A tooling-, CI-, or flake-only change ships no
+  release, so it needs no fragment.
+- A fork's scriv section documents the Lua fork's own release line; the inherited
+  upstream changelog stays below it as history.
+
+## Releasing ([ADR 0006](docs/adr/0006-fork-release-by-annotated-tag.md), [ADR 0009](docs/adr/0009-changelogs-via-scriv.md))
+
+Run `scriv collect --version <tag>` to fold the pending fragments into
+`CHANGELOG.md`, then commit it with the version bump. After that: annotated git
+tag on `master` → bump the fork's version in `src/packages.json` → regenerate the
+README package table (`scripts/gen-readme-table.sh`) → refresh
+`latest-compatible-sets.json` → push a `psc-*` set tag. A tooling-only PR needs no
+release.
 
 A `psc-*` tag publishes one release asset
 ([ADR 0008](docs/adr/0008-new-spago-and-json-package-set.md)): `packages.json`,

changelog.d/scriv.ini

@@ -0,0 +1,9 @@
+[scriv]
+format = md
+md_header_level = 2
+categories = Added, Changed, Fixed, Removed
+# Hyphen separator (Keep a Changelog style), not scriv's default em dash, so
+# collected entries match the hand-written backfill. The `%` are doubled
+# because scriv reads this file with configparser interpolation, which treats a
+# bare `%` specially; `%%` is an escaped literal `%`.
+entry_title_template = {%% if version %%}{{ version }} - {%% endif %%}{{ date.strftime('%%Y-%%m-%%d') }}

docs/adr/0006-fork-release-by-annotated-tag.md

@@ -1,6 +1,6 @@
 # 0006 — Release forks with annotated tags
 
-Status: Accepted
+Status: Accepted (the no-changelog clause is superseded by [0009](0009-changelogs-via-scriv.md))
 
 ## Context
 

docs/adr/0009-changelogs-via-scriv.md

@@ -0,0 +1,66 @@
+# 0009 — Keep changelogs with scriv
+
+Status: Accepted (supersedes the no-changelog clause of [0006](0006-fork-release-by-annotated-tag.md))
+
+## Context
+
+[0006](0006-fork-release-by-annotated-tag.md) decided that a fork release is a
+bare annotated tag with no GitHub Release and no changelog entry, on the grounds
+that a per-release changelog would be over-process for a tag-driven fork.
+
+The pre-release FFI campaign changed that calculus. Between #73 and #102 the
+forks took a run of behavioural fixes — `Char` code-point handling in enums,
+32-bit `Int` semantics in integers, the `Number` formatting contract in numbers,
+`forE`/`ST.for` range fixes in effect and st, and more. The fork tags carry one
+line each, and the only place those lines are aggregated is the set-bump commit
+messages in this repository. A consumer pinning, say, numbers v9.1.3 has no way
+to read what moved between v9.1.0 and v9.1.3 without walking the git log of two
+repositories. The same gap exists for the compiler and for the set itself.
+
+So the tradeoff flipped: the cost of a missing changelog now exceeds the cost of
+maintaining one, especially once the FFI work is the thing people most need to
+diff between versions.
+
+## Decision
+
+Every repository in the ecosystem keeps a `CHANGELOG.md` managed with
+[scriv](https://scriv.readthedocs.io/): change fragments live in `changelog.d/`,
+and `scriv collect --version <tag>` assembles them into a dated section on
+release. This covers the [pslua compiler](https://github.com/purescript-lua/purescript-lua),
+every set fork, and this set repository.
+
+Concretely, per repository:
+
+- A scriv config (`changelog.d/scriv.ini`): Markdown output, `md_header_level = 2`,
+  categories `Added, Changed, Fixed, Removed`, and a hyphen entry-title separator
+  so collected sections read as `## <version> - <date>` in the Keep a Changelog
+  shape. The `%` in the title template are doubled (`%%`) because scriv reads the
+  file through configparser interpolation.
+- `scriv` in the dev shell. The forks add it to their `flake.nix` `buildInputs`;
+  this set repository and any other flake-less consumer get it from the pslua dev
+  shell (`nix develop github:purescript-lua/purescript-lua`), which carries it.
+- A `CHANGELOG.md` seeded with the `<!-- scriv-insert-here -->` /
+  `<!-- scriv-end-here -->` markers. Forks keep their inherited upstream history
+  below the fork section; the scriv-managed region documents the Lua fork's own
+  release line.
+
+This reverses the no-changelog clause of [0006](0006-fork-release-by-annotated-tag.md).
+The rest of 0006 stands: a fork release is still an annotated tag on `master`
+followed by a `src/packages.json` bump and a `psc-*` set tag, and a tooling-only
+change still needs no release.
+
+## Consequences
+
+- A change that touches `src/` adds a `changelog.d/` fragment in the same change.
+  Tooling/CI/flake-only changes do not need one (they ship no release), matching
+  the tag rule in 0006.
+- On release, run `scriv collect --version <tag>` before tagging, review the
+  assembled section, and commit it with the version bump. The annotated tag still
+  points at that commit. There is no GitHub Release for a fork; the changelog is
+  the human-readable record.
+- The retroactive backfill prioritised the FFI campaign tags (#73–#102); older
+  upstream-inherited versions are left to the inherited upstream changelog rather
+  than reconstructed.
+- CONTRIBUTING's release section and each fork's `AGENTS.md` "Releasing" note are
+  updated to require the fragment and the collect step. The "no changelog entry"
+  wording in those files is removed.

docs/adr/README.md

@@ -36,3 +36,4 @@ The practical, do-this summary of these decisions is in the repository root
 - [0006](0006-fork-release-by-annotated-tag.md) — Release forks with annotated tags
 - [0007](0007-formatting-treefmt-purs-tidy-lua-format.md) — Formatting via treefmt: purs-tidy and lua-format
 - [0008](0008-new-spago-and-json-package-set.md) — Publish a consumable JSON package set for the new spago
+- [0009](0009-changelogs-via-scriv.md) — Keep changelogs with scriv