From 20497baa8cb6f6ae466d5f7a221326a7ff906e55 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 16:59:59 +0000 Subject: [PATCH 1/3] Document the fz 2.0 release - Release notes: "Unreleased (main branch, after 1.2)" becomes "Version 2.0", with why it is a major version; add the default-delimiter warning (Funz/fz#104), the manifest fz_version fix (Funz/fz#103), the release tooling (Funz/fz#105) and the plugin/skill version. - Constraints: "fz after Funz/fz#99" -> "fz 2.0"; Python 3.14 is tested in CI (it said pre-release only); mirror the delimiter warning of doc/limitations.md. - Template syntax and troubleshooting: the delimiter warning. - Contributing: release process (single version source, check_dist.py, wheel verified on the CI matrix, tag must equal fz.__version__). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RjXvVRjM6aMvKvvSFoxpZ6 --- docs/contributing/development.md | 16 ++++++++++++---- docs/reference/limitations.md | 10 +++++++--- docs/reference/releases.md | 23 ++++++++++++++++++++--- docs/reference/troubleshooting.md | 1 + docs/user-guide/templates/syntax.md | 5 +++-- 5 files changed, 43 insertions(+), 12 deletions(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index f52a3f3..71f4a87 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -51,10 +51,18 @@ changes: `README.md` (overview, under 300 lines), `doc/` (one file per topic), a ## Releasing -`fz/_version.py` is stamped by CI (`scripts/stamp_version.py`) and must not be edited by -hand; `pyproject.toml` reads the version dynamically. A release commit folds `## Unreleased` into a dated `## Version X.Y` section in -`NEWS.md`, and aligns the Claude Code plugin version. Publishing a GitHub Release with -the matching tag triggers `release.yml`, which pushes to PyPI. +The version number lives in `fz/__init__.py` only (`pyproject.toml`, `fz --version` and +`manifest.json` read it). `fz/_version.py` holds the commit date and hash; `release.yml` +stamps it (`scripts/stamp_version.py`) and it must not be edited by hand. A release +commit folds `## Unreleased` into a dated `## Version X.Y` section in `NEWS.md`, and +aligns the Claude Code plugin version. + +Publishing a GitHub Release triggers `release.yml`. It builds the wheel and the sdist +once, checks them with `scripts/check_dist.py` (one pure-Python wheel, `twine check`, +release tag equal to `fz.__version__`, a leading `v` being allowed), installs the wheel +on the CI OS × Python matrix with a smoke test, then publishes to PyPI and attaches the +files to the release. A tag that does not match the version stops the release before +anything is published. ## See Also diff --git a/docs/reference/limitations.md b/docs/reference/limitations.md index cf0b63a..b5e7560 100644 --- a/docs/reference/limitations.md +++ b/docs/reference/limitations.md @@ -3,13 +3,14 @@ This page lists the behaviors of fz that most often surprise users. Each item states the rule, the consequence, and what to do instead. Items were checked against the code of fz (`fz/core.py`, `fz/helpers.py`, `fz/runners/`, `fz/config.py`, `fz/cli.py`) and by running it. They -describe fz after Funz/fz#99; fz ≤ 1.2 differs on timeouts `0`, default delimiters, +describe fz 2.0; fz ≤ 1.2 differs on timeouts `0`, default delimiters, `fz list` and global installs. Source: [`doc/limitations.md`](https://github.com/Funz/fz/blob/main/doc/limitations.md). ## Platform and dependencies -- **Python ≥ 3.9.** 3.9–3.13 are tested in CI; 3.14 is exercised as a pre-release only. +- **Python ≥ 3.9.** 3.9–3.14 are tested in CI on Linux, macOS and Windows (3.9 not on + Windows). - **bash is required everywhere.** Calculator commands and shell output parsers run through bash. On Windows, install MSYS2 or Git Bash and point `FZ_SHELL_PATH` at its `bin` directories (see [Environment Variables](environment.md#general)). Shell-free output parsers @@ -26,7 +27,10 @@ describe fz after Funz/fz#99; fz ≤ 1.2 differs on timeouts `0`, default delimi - **Default delimiters.** A model without `delim` (nor `var_delim`) accepts both `$(x)` and `${x}` for variables and uses `@{...}` for formulas; the CLI without `--model` uses the same default. Setting `"delim": "{}"` or `"()"` restricts variables to one form. - Templates that contain other `${...}` text (shell snippets) should set `delim`. + Templates that contain other `${...}` text (shell snippets) should set `delim`: + `fzi` (hence `fzc`/`fzr`) logs a warning (`FZ_LOG_LEVEL=WARNING` or lower) when + `${...}` names sit next to `$(...)` variables in a model without `delim`, and the + `input_variables is required` error names the `${...}`-only variables. - **No automatic `?var` conversion.** `?var` is a variable only with `"varprefix": "?"`. - A variable absent from `input_variables` and without `~default` is left as-is in the compiled file (no error from `fzc`). diff --git a/docs/reference/releases.md b/docs/reference/releases.md index 1a8db6b..397f7ea 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -3,7 +3,11 @@ Complete, authoritative notes: [NEWS.md](https://github.com/Funz/fz/blob/main/NEWS.md) in the fz repository. -## Unreleased (main branch, after 1.2) +## Version 2.0 (2026-11-06) + +2.0 is a major version because it changes behavior in ways that are not backward +compatible (summary below). It also fixes wrong results with some `sh://` commands and +a command-injection issue present in 1.2: upgrading is recommended. !!! warning "Behavior changes when upgrading from 1.2" - Python 3.8 is no longer supported (`requires-python >= 3.9`). @@ -55,8 +59,21 @@ in the fz repository. - An unexpected exception in one case no longer aborts a sequential campaign: the case gets `status="error"` with the message in the `error` column (Funz/fz#100). - `fzo` decodes percent-encoded case directory names when rebuilding variable columns. -- Claude Code plugin / Agent Skill updated for all the above (plugin manifests to be - bumped with the release). +- Claude Code plugin / Agent Skill updated for all the above; plugin version 2.0.0. The + skill now documents every name exported by `fz` and every `fz` subcommand (checked by + `tests/test_skill_static.py`). +- **Default delimiters warning** (Funz/fz#104): when a model without `delim` has `${...}` + names next to `$(...)` variables (typically shell text such as `${HOME}`), `fzi` (hence + `fzc`/`fzr`/`fzd`) logs a warning (visible with `FZ_LOG_LEVEL=WARNING` or lower), and + the `input_variables is required` error names the `${...}`-only variables. Results are + unchanged. +- `manifest.json` (`fz_version`, RO-Crate) reported version `1.0`; it now reports the + installed version (Funz/fz#103). +- **Release tooling** (Funz/fz#105): the pure-Python wheel and the sdist are built once + and checked (`scripts/check_dist.py`: one `py3-none-any` wheel, `twine check`, release + tag equal to the version); `release.yml` installs and smoke-tests the wheel on the CI + OS × Python matrix before publishing, and `ci.yml` installs it in a fresh venv on every + push and pull request. - Error reports no longer blame the command for a "not found" printed by the code. - `fz/runners.py` split into the `fz.runners` package (no behavior change; code patching `fz.runners.run_command` must patch `fz.runners.sh.run_command`). diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 2430ec0..7f07a9a 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -15,6 +15,7 @@ fz.set_log_level("DEBUG") # or FZ_LOG_LEVEL=DEBUG before starting Python | `Permission denied ... ./input.txt` | No calculator: fz fell back to an empty `sh://` | Give `calculators`, or install a calculator alias matching the model `id` | | `fzi` misses `${x}` (fz ≤ 1.2) or `$(x)` variables | Model sets `delim` to the other pair (or fz ≤ 1.2 default `()`) | Fix `delim`, or remove it to accept both forms | | `fzi` reports unexpected variables | `varprefix` collides with the code's syntax | Change `varprefix` (e.g. `%`) | +| `fzi` lists `HOME` (or other shell `${...}` names); warning `The model sets no "delim"` | A model without `delim` reads `${x}` as well as `$(x)` | Set `"delim": "()"` (or `"{}"`) in the model | | Case `done` but output `None` and `error` = `Missing output: ...` | Extractor found nothing: wrong file/pattern, file written elsewhere, locale | Test the extractor with `fzo` on the case directory | | Output value equals the program's stdout | The code writes `out.txt` (reserved, overwritten by stdout) | Rename the code's output file | | Result file contains the input twice, or the command gets unexpected arguments | The compiled input names are appended to the end of the `sh://` command line | Move file handling into a script run as `sh://bash script.sh` | diff --git a/docs/user-guide/templates/syntax.md b/docs/user-guide/templates/syntax.md index 1641979..5cad728 100644 --- a/docs/user-guide/templates/syntax.md +++ b/docs/user-guide/templates/syntax.md @@ -9,8 +9,9 @@ in the [model](../models/definition.md); this page uses `varprefix="$"`, A model **without** `delim` accepts both `$(x)` (Java Funz convention) and `${x}` for variables, and `@{...}` for formulas; the CLI without `--model` does the same. Set `delim` when the code's own text contains `${...}` or `$(...)` that must not be read - as variables. In fz ≤ 1.2, a model without `delim` only recognized `$(x)` and the CLI - only `${x}`. + as variables. fz logs a warning (`FZ_LOG_LEVEL=WARNING` or lower) when, in a model + without `delim`, `${...}` names appear next to `$(...)` variables. In fz ≤ 1.2, a model + without `delim` only recognized `$(x)` and the CLI only `${x}`. ## Variables From 10f74bd2657cf7ec18e86048dde6cc7c421632d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 03:16:46 +0000 Subject: [PATCH 2/3] Release notes: date 2.0 2026-11-07 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RjXvVRjM6aMvKvvSFoxpZ6 --- docs/reference/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/releases.md b/docs/reference/releases.md index 397f7ea..bc9cc8e 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -3,7 +3,7 @@ Complete, authoritative notes: [NEWS.md](https://github.com/Funz/fz/blob/main/NEWS.md) in the fz repository. -## Version 2.0 (2026-11-06) +## Version 2.0 (2026-11-07) 2.0 is a major version because it changes behavior in ways that are not backward compatible (summary below). It also fixes wrong results with some `sh://` commands and From 83209c62768d9fdae7e11fd8a3f8ed58dbf34ef5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 16:58:32 +0000 Subject: [PATCH 3/3] Release notes: 2.0 published 2026-11-08; add Funz/fz#107, #108, #111 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RjXvVRjM6aMvKvvSFoxpZ6 --- docs/reference/releases.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/reference/releases.md b/docs/reference/releases.md index bc9cc8e..d79ba1b 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -3,7 +3,7 @@ Complete, authoritative notes: [NEWS.md](https://github.com/Funz/fz/blob/main/NEWS.md) in the fz repository. -## Version 2.0 (2026-11-07) +## Version 2.0 (2026-11-08) 2.0 is a major version because it changes behavior in ways that are not backward compatible (summary below). It also fixes wrong results with some `sh://` commands and @@ -74,6 +74,12 @@ a command-injection issue present in 1.2: upgrading is recommended. tag equal to the version); `release.yml` installs and smoke-tests the wheel on the CI OS × Python matrix before publishing, and `ci.yml` installs it in a fresh venv on every push and pull request. +- `fzd` with a file-based model no longer leaves an empty `iterNNN_/` + directory next to each `iterNNN/` of its `analysis_dir` (Funz/fz#108). +- A failed `#require:` auto-install of an algorithm now reports pip's output; the error + ended with an empty `Error:` (Funz/fz#111). +- The Agent Skill was audited against the code (Funz/fz#107): among others, the `fzd` + example passed `max_iterations` to `bfgs.py`, which reads `max_iter`. - Error reports no longer blame the command for a "not found" printed by the code. - `fz/runners.py` split into the `fz.runners` package (no behavior change; code patching `fz.runners.run_command` must patch `fz.runners.sh.run_command`).