diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..1608054a --- /dev/null +++ b/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. + + + +## 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. + + + +[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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cb92ca0..1a008839 100644 --- a/CONTRIBUTING.md +++ b/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 ` 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`, diff --git a/changelog.d/scriv.ini b/changelog.d/scriv.ini new file mode 100644 index 00000000..1f8b4560 --- /dev/null +++ b/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') }} diff --git a/docs/adr/0006-fork-release-by-annotated-tag.md b/docs/adr/0006-fork-release-by-annotated-tag.md index 2c8102ed..75b71c42 100644 --- a/docs/adr/0006-fork-release-by-annotated-tag.md +++ b/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 diff --git a/docs/adr/0009-changelogs-via-scriv.md b/docs/adr/0009-changelogs-via-scriv.md new file mode 100644 index 00000000..70d00b4c --- /dev/null +++ b/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 ` 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 `## - ` 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 `` / + `` 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 ` 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. diff --git a/docs/adr/README.md b/docs/adr/README.md index e5c8d56d..f4d0d5f6 100644 --- a/docs/adr/README.md +++ b/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