[FBumann]

Prompt: Ok. SO we can release 0.4.0 now? Prepare the release PR

Note

The following content was generated by AI.

What this changes

This PR renames ## Upcoming version to ## 0.4.0 (2026-10-21) and edits the section into the release notes. The diff is CHANGELOG.md alone. When this PR merges, the workflow tags v0.4.0 and publishes the package. This PR replaces #884.

The opening paragraph is the user's own text. The rest was rewritten at the user's request: "Rewrite the whole changelog", limited to the 0.4.0 section. Two later prompts set scope: "Update the 0.4.0 release PR accordingly" added #931 and #934 after they merged, and "Can we shorten each bullet point to the actually relevant, actionable thing for a user?" cut each migration bullet to what to change.

What the section holds

• The opening paragraph explains the change from masks: to conditions:, and what a condition and a mask are. It also says that most modules are now private.
• What to change in a spec file: refactor(language)!: a file names a condition under conditions: rather than masks: #907, fix(language)!: a named expression whose dims: gives a dimension its expression is not indexed over is refused at load #898, fix(language)!: a condition that uses <, <=, > or >= on a str or bool value is refused at load #931, feat(cli)!: python -m mathspec diff compares two specs in the canonical form, and canonical no longer rewrites or checks a file #874, fix(language): two files that declare their dimensions in different orders load to the same program #911 with feat(program): each expression node states the dimensions it is read over #899, and feat(spec)!: a spec written back out puts short lists and mappings of names on one line #871. Each item says what to change, in one sentence, with no reason.
• What to change in Python code: refactor(api)!: a module outside spec, program and errors has a name that starts with an underscore #878, refactor(api)!: a spec class ends in Spec, a program class takes its construct's name, and the docs call one named item an entry #855, refactor(api)!: the docs, the error messages and the program classes call a true-or-false where expression a condition rather than a predicate #904, refactor(language)!: a file names a condition under conditions: rather than masks: #907 and feat(program): each expression node states the dimensions it is read over #899, and the moved reference page. A table maps the four mathspec.program names whose meaning changed (Parameter, Variable, NamedExpression, NamedMask). Code that uses an old meaning raises no error, so that item keeps its one-sentence warning. The table goes from 0.3.x straight to 0.4.0, so it includes refactor(language)!: a file names a condition under conditions: rather than masks: #907's renames on top of refactor(api)!: a spec class ends in Spec, a program class takes its construct's name, and the docs call one named item an entry #855's.
• The 17 PRs, in six groups. Each line keeps its type, its ! and its link. The subject is rewritten as a plain sentence, so a line no longer matches its PR title word for word. feat(program): each expression node states the dimensions it is read over #899's line also gains a !, because every expression node now has a required dims field. These are all the PRs on main since v0.3.0. fix(language): a case-when whose cases test different columns of one relation is refused when one row can meet both #934 merged into fix(language)!: a condition that uses <, <=, > or >= on a str or bool value is refused at load #931's branch, so it has a line but no commit of its own on main. chore: the private names for parsing and resolving a condition say condition rather than where #909 is a chore and adds no line.

Why

#884 was written on 2026-10-15 for seven PRs. Since then, ten more PRs have merged. Its notes also say that a 0.3.0 file still loads, which #907, #898 and #931 have made false. This branch starts again from main, because #884 is 46 merge commits deep.

Checks, and what was not done

Gates on 12bc26e:

• pixi run python -m tools.changelog check: releases 0.4.0 on merge.
• pixi run lint: passed.
• pixi run docs-build: no issues found.
• pixi run test passed on acc2e3d (the merge of main at 6088835, fix(language)!: a condition that uses <, <=, > or >= on a str or bool value is refused at load #931): 3065 passed, 1 skipped. Later commits change only CHANGELOG.md.
• compile-tex did not run. The session container cannot download the tectonic bundle, and CHANGELOG.md does not affect it. CI runs it.

Claims checked against the code:

• A top-level masks: is refused with unknown key 'masks' in the top level of the file. Valid keys: ….
• A where: inside a conditions: entry is refused with Valid keys: condition, description.
• program.Sum takes dims as a required keyword.
• SUPPORTED_VERSIONS is (0,) on both v0.3.0 and main.
• The class names in the table are compared with __all__ of mathspec.program and mathspec.spec on v0.3.0 and on main.
• fix(language): a patch that changes a dimension is told that a field it leaves out reads as its default #857's line was checked against the message it adds.
• At v0.3.0, expressions.md says that str labels compare bytewise, so the fix(language)!: a condition that uses <, <=, > or >= on a str or bool value is refused at load #931 item is a change from 0.3.x. The column-blind relation subject that fix(language): a case-when whose cases test different columns of one relation is refused when one row can meet both #934 fixes is in v0.3.0 too (exclusivity.py:312).

Not done:

• The shortening drops the reasons and two facts: that fix(language)!: a named expression whose dims: gives a dimension its expression is not indexed over is refused at load #898 also refuses a merge whose sum names a dimension no term is indexed over, and the g, t example for fix(language): two files that declare their dimensions in different orders load to the same program #911. The loader's message names the rewrite in each case.
• The headline says "most files written for 0.3.x". That is the user's wording. At v0.3.0, 16 of the 62 example specs use masks:.
• The date is today's. If this PR merges on another day, change the heading to the day it merges.
• No new, empty ## Upcoming version is added above the release. The next PR that owes a changelog line adds it.
• The sections of releases before 0.4.0 are not changed.
• The open PRs labelled v0.4.0 (feat(language)!: a missing row reads as the value the file names, and missing: neutral is gone #894, docs(pypsa): a PyPSA schedule, weight or limit that the data leaves out is absent rather than zero, and a committable extendable unit is assumed to have its big-M #912, feat(spec): a spec writes back the fields its file wrote, and the canonical form writes no default #918, feat(spec)!: a loaded spec cannot be changed, so the file it writes back out is always the one its program comes from #923, feat(spec)!: a loaded spec is sorted by name and cannot be changed, writes back the fields its file wrote, and prints one canonical text for two files that differ only in order or spelling #924) are not in this release. They go into the next one. fix(language)!: a condition that uses <, <=, > or >= on a str or bool value is refused at load #931 was labelled v0.5.0, but it is on main, so it ships in 0.4.0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B5NaERV1RNkFNcrngYUefA
https://claude.ai/code/session_015vU4ni6oQbTr8PM7EaYqDu

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #35298611 | 📁 Comparing 12bc26e against latest (0f892c0)

  🔍 Preview build  

2 files changed

± reference/changelog/index.html
± reference/language/expressions/index.html

[brynpickering]

Let's do it

[FBumann]

@brynpickering We should have updated the date. I wont fix it, but we need to take care next time.