From b0830111d4bb4bc6e640f03d94b21068671aaa56 Mon Sep 17 00:00:00 2001 From: Stephen Aylward Date: Tue, 25 Aug 2026 17:45:59 -0400 Subject: [PATCH 1/2] ENH: Change policy to favor and document backward compatibility --- .agents/agents/implementation.md | 12 +++++-- .agents/skills/check-conventions/SKILL.md | 8 +++++ .agents/skills/commit/SKILL.md | 23 ++++++++++--- .agents/skills/impl/SKILL.md | 11 ++++-- .cursor/rules/project-standards.mdc2 | 21 +++++++----- AGENTS.md | 33 ++++++++++++++++-- CLAUDE.md | 17 ++++++++-- docs/contributing.rst | 17 +++++++++- docs/developer/ai_assistants.rst | 7 ++++ docs/developer/architecture.rst | 6 ++++ docs/developer/extending.rst | 1 + docs/developer/migration_next.md | 41 +++++++++++++++++++++++ docs/index.rst | 2 ++ utils/ai_agent_github_reviews.py | 3 +- 14 files changed, 176 insertions(+), 26 deletions(-) create mode 100644 docs/developer/migration_next.md diff --git a/.agents/agents/implementation.md b/.agents/agents/implementation.md index 7e18a4a0..8334f214 100644 --- a/.agents/agents/implementation.md +++ b/.agents/agents/implementation.md @@ -1,6 +1,6 @@ --- name: PhysioTwin4D Implementation Agent -description: Implements features, bug fixes, or refactors in PhysioTwin4D. Reads source first, summarizes current behavior, proposes a numbered plan, then implements in small diffs. Calls out breaking changes. +description: Implements features, bug fixes, or refactors in PhysioTwin4D. Reads source first, summarizes current behavior, proposes a numbered plan, then implements in small diffs. Calls out breaking changes and logs them in the migration guide. tools: Read, Edit, Write, Bash, Glob, Grep --- @@ -24,7 +24,9 @@ searching manually. 3. Propose a numbered implementation plan. For non-trivial changes, stop and confirm. 4. Implement in the smallest reviewable diff possible. 5. Update docstrings and type hints for every changed public method. -6. Note any breaking changes explicitly. +6. Note any breaking changes explicitly, and append an entry for each one to + `docs/developer/migration_next.md` using the template at the bottom of that + file. ## Code rules @@ -61,7 +63,11 @@ searching manually. ## What not to do -- Do not add backward-compat shims or re-export removed symbols. +- Do not break a public API unless the change is generally beneficial to future + users; prefer compatibility. +- Do not add deprecation shims or re-export removed symbols. Log the break in + `docs/developer/migration_next.md` and, when the change is substantial, ship + a script that automates the conversion. - Do not add error handling for impossible internal states. - Do not create new files when editing an existing one suffices. - Do not add features beyond what was requested. diff --git a/.agents/skills/check-conventions/SKILL.md b/.agents/skills/check-conventions/SKILL.md index 21924b16..b3cac592 100644 --- a/.agents/skills/check-conventions/SKILL.md +++ b/.agents/skills/check-conventions/SKILL.md @@ -62,6 +62,14 @@ context such as class inheritance), then flag every occurrence of: or return value means. Only genuine deviations from the conventions in `CLAUDE.md` may be documented. +### Migration guide +- [ ] A deprecation shim, alias, or re-export kept solely for backward + compatibility. Break the API instead, and provide a conversion script. +- [ ] A public class, method, CLI flag, or signature that the diff renames, + removes, or changes, with no matching entry in + `docs/developer/migration_next.md`. Report the missing entry against the + changed line. + ## Output Group findings by file. For each finding, print: diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md index 6a940c84..9f32da8e 100644 --- a/.agents/skills/commit/SKILL.md +++ b/.agents/skills/commit/SKILL.md @@ -20,13 +20,26 @@ Instructions: that should not be committed, display an error, stop processing, and abort - Do NOT add any untracked files to the commit. -2. Draft a commit message following the project convention (match style of recent `git log --oneline -10`): +2. Scan the diff for breaking changes to the public API — renamed or removed + classes, methods, or CLI flags, changed signatures or defaults, changed + output file layouts. + - If there are none, continue. + - If there are any, append one entry per break to + `docs/developer/migration_next.md` before committing, following the + template at the bottom of that file: what changed, why it benefits future + users, before/after code, and the script that automates the conversion + (or `None needed`). Remove the `_No breaking changes recorded since ..._` + placeholder line once the first entry is added. + - `migration_next.md` is tracked, so `git commit -a` picks it up. + - Do not resolve a break by adding a deprecation shim or a re-export. + +3. Draft a commit message following the project convention (match style of recent `git log --oneline -10`): - Subject line: `: ` (≤72 chars), where TAG is one of: `ENH` (new feature / enhancement), `FIX` (bug fix), `REF` (refactor), `TST` (tests only), `DOC` (docs/comments only), `MNT` (maintenance / config). - Optional body: 1–3 sentences explaining *why*, not *what*. -3. Attempt the commit. Include a body only when it adds meaningful context: +4. Attempt the commit. Include a body only when it adds meaningful context: ```bash git commit -a -m "" -m "" ``` @@ -35,7 +48,7 @@ Instructions: git commit -a -m "" ``` -4. If the commit fails because a pre-commit hook rejected it: +5. If the commit fails because a pre-commit hook rejected it: a. Read the hook output carefully. b. Fix every reported issue (formatting, lint errors, type errors, test failures, etc.). - For `ruff` formatting/lint: use `git diff --diff-filter=d --name-only HEAD -- '*.py'` @@ -43,8 +56,8 @@ Instructions: `ruff check --fix` and `ruff format`. Do not run ruff project-wide. - For `mypy` errors: fix the type annotations in the flagged files. - For other hook failures: diagnose and fix the root cause; do NOT use `--no-verify`. - c. Return to step 3 and retry — repeat until the commit succeeds or you have exhausted reasonable fixes. + c. Return to step 4 and retry — repeat until the commit succeeds or you have exhausted reasonable fixes. d. If an issue cannot be fixed automatically (e.g. a failing test unrelated to the current changes), report it to the user and stop. -5. After a successful commit, print the one-line commit summary (`git log --oneline -1`) +6. After a successful commit, print the one-line commit summary (`git log --oneline -1`) and remind the user: "Remember to `git push` when you are ready to publish this commit." diff --git a/.agents/skills/impl/SKILL.md b/.agents/skills/impl/SKILL.md index 1250e707..67969a67 100644 --- a/.agents/skills/impl/SKILL.md +++ b/.agents/skills/impl/SKILL.md @@ -1,5 +1,5 @@ --- -description: Read relevant PhysioTwin4D source files, summarize current behavior, propose a brief plan, then implement the requested feature or refactor in small diffs. Calls out breaking changes. +description: Read relevant PhysioTwin4D source files, summarize current behavior, propose a brief plan, then implement the requested feature or refactor in small diffs. Calls out breaking changes and logs them in the migration guide. --- Implement the following in the PhysioTwin4D repository: @@ -13,5 +13,10 @@ Instructions: 4. Implement in the smallest reviewable diff possible. 5. Update docstrings and type hints for every changed public method. 6. Run `ruff check . --fix && ruff format .` after editing Python files. -7. Explicitly note any breaking changes introduced. -8. Do not add features beyond what was requested. +7. Prefer compatibility. Break a public API only when the change is generally + beneficial to future users, and never via a deprecation shim — provide a + conversion script when the change is substantial. +8. Explicitly note any breaking changes introduced, and append an entry for + each to `docs/developer/migration_next.md` using the template at the bottom + of that file. +9. Do not add features beyond what was requested. diff --git a/.cursor/rules/project-standards.mdc2 b/.cursor/rules/project-standards.mdc2 index 4413fa35..83c496bb 100644 --- a/.cursor/rules/project-standards.mdc2 +++ b/.cursor/rules/project-standards.mdc2 @@ -44,14 +44,19 @@ git mv old_name.py new_name.py - Update existing README.md files when needed - API documentation in existing docs structure -## Backward Compatibility - -**Backward compatibility is NOT a priority** for this project: - -- Feel free to make breaking changes to improve code quality -- Remove deprecated code without extensive migration paths -- Update APIs for clarity and consistency -- Prioritize modern, clean design over legacy support +## Compatibility and Migration + +**Prefer compatibility.** Break a public API only when the change is generally +beneficial to future users: + +- Do not add deprecation shims or removed-symbol re-exports +- When a break is substantial, ship code that automates the conversion instead +- Every commit that breaks a public API adds an entry to + `docs/developer/migration_next.md` in that same commit — what changed, why it + benefits future users, before/after code, and the conversion script +- At release: `git mv docs/developer/migration_next.md + docs/developer/migration_.md`, retitle it, and start a fresh + `migration_next.md` from its entry template ## Code Style diff --git a/AGENTS.md b/AGENTS.md index 827335c7..38d16bce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,8 +8,9 @@ medical image of a subject, extracting anatomic models, and then using AI surrogates to estimate the subject's physiological processes (initially cardiac and respiratory motion, expanding to electrophysiology, blood flow, and organ perfusion). It is an **early-alpha** scientific Python library. -Clarity beats premature optimization. Breaking changes are acceptable. -Backward compatibility is not a goal. +Clarity beats premature optimization. Prefer compatibility: break a public API +only when the change is generally beneficial to future users, and record every +break in the migration guide (see below). ## Role @@ -98,6 +99,30 @@ python -m pytest tests/ --create-baselines Version bumping: `bumpver update --patch`, `--minor`, or `--major`. +## Migration Guide + +PhysioTwin4D prefers compatibility. Break a public API only when the change is +generally beneficial to future users. Never add deprecation shims or +removed-symbol re-exports; when a break is substantial, ship code that +automates the conversion instead. + +At commit time: if the diff breaks a public API, append an entry to +`docs/developer/migration_next.md` in that same commit — what changed, why it +benefits future users, before/after code, and the conversion script (or +`None needed`). Follow the entry template at the bottom of that file. + +At release time: + +```bash +bumpver update --patch +git mv docs/developer/migration_next.md docs/developer/migration_.md +# retitle the archived file to "Migration Guide - " +# recreate docs/developer/migration_next.md from its entry template +``` + +The `Developer Guides` toctree in `docs/index.rst` globs +`developer/migration_*`, so archived guides need no further wiring. + ## graphify This project keeps a knowledge graph at `graphify-out/` covering god nodes, @@ -191,7 +216,9 @@ graphify update . # refresh after code changes (AST-only, no API c changes. - Keep diffs small and reviewable. - Prefer editing existing modules over creating new ones. -- No backward-compatibility shims: just change the code. +- No deprecation shims or removed-symbol re-exports. Change the code, log the + break in `docs/developer/migration_next.md`, and provide a conversion script + when the change is substantial. ## Testing Role diff --git a/CLAUDE.md b/CLAUDE.md index c8401783..f8a307bd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -71,7 +71,16 @@ Strong success criteria let you loop independently. Weak criteria ## 5. Project-Specific Rules -- Breaking changes are acceptable. Backward-compatibility shims are not. +- Prefer compatibility. Break a public API only when the change is generally + beneficial to future users. +- Never add deprecation shims or removed-symbol re-exports. When a break is + substantial, ship code that automates the conversion instead. +- Every commit that breaks a public API must add an entry to + `docs/developer/migration_next.md`: what changed, why it benefits future + users, before/after code, and the conversion script (or `None needed`). +- At release time, `git mv docs/developer/migration_next.md + docs/developer/migration_.md`, retitle it, and start a fresh + `migration_next.md` from its entry template. --- @@ -174,12 +183,16 @@ Use `git mv` / `git rm` — not `mv` / `rm` — to preserve history. Do **not** create new `.md` files unless explicitly requested. Document via docstrings and inline comments. +Exception: the migration guide. Append to `docs/developer/migration_next.md` +whenever a commit breaks a public API, and create +`docs/developer/migration_.md` plus a fresh `migration_next.md` at +release time. + ## Code Style - Double quotes for strings and docstrings - Full type hints (`mypy` strict; `disallow_untyped_defs = true`) - `Optional[X]` not `X | None` (ruff `UP007` suppressed) -- Breaking changes are acceptable — backward compatibility is not a priority - Max line length: 88 characters - Follow behavior guidelines. diff --git a/docs/contributing.rst b/docs/contributing.rst index a20c08bd..ddc5de2b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -231,6 +231,10 @@ Pull Request Guidelines * **Pass all tests**: CI must pass * **Update documentation**: Document new features * **Add release note**: Document user-facing changes in the pull request +* **Log breaking changes**: If the change breaks a public API, add an entry to + ``docs/developer/migration_next.md`` in the same commit, covering what + changed, why it benefits future users, before/after code, and the script that + automates the conversion. Do not add deprecation shims instead. Testing ======= @@ -375,7 +379,9 @@ Review Criteria * **Tests**: Are there adequate tests? * **Documentation**: Is it properly documented? * **Performance**: Are there any performance concerns? -* **Compatibility**: Does it maintain backwards compatibility? +* **Compatibility**: Does it avoid needless breaking changes, and is every + unavoidable break recorded in ``docs/developer/migration_next.md`` with a + conversion path rather than a deprecation shim? Reporting Issues ================ @@ -427,12 +433,21 @@ Maintainers only: # Bump version bumpver update --patch + # Archive the migration guide under the new version, then start a fresh one + git mv docs/developer/migration_next.md docs/developer/migration_.md + # Retitle the archived file to "Migration Guide - " + # Recreate docs/developer/migration_next.md from its entry template + # Build package python -m build # Upload to PyPI python -m twine upload dist/* +The ``Developer Guides`` toctree in ``docs/index.rst`` globs +``developer/migration_*``, so archived guides appear in the sidebar without +further edits. + Community Guidelines ==================== diff --git a/docs/developer/ai_assistants.rst b/docs/developer/ai_assistants.rst index f01d0648..00b4e567 100644 --- a/docs/developer/ai_assistants.rst +++ b/docs/developer/ai_assistants.rst @@ -13,6 +13,12 @@ assistant; ``CLAUDE.md`` adds Claude-specific instructions. Role subagents live in ``.agents/agents/`` and slash-command skills in ``.agents/skills/``. Read those before hand-writing a prompt that repeats project conventions. +One of those conventions binds every assistant: PhysioTwin4D prefers +compatibility, breaks a public API only when the change is generally beneficial +to future users, and never ships deprecation shims. Any commit that does break +an API must add an entry to :doc:`migration_next` describing the change and the +code that automates the conversion. + graphify ======== @@ -49,4 +55,5 @@ See Also * :doc:`core` * :doc:`extending` +* :doc:`migration_next` * :doc:`../contributing` diff --git a/docs/developer/architecture.rst b/docs/developer/architecture.rst index 8cd68858..8695897c 100644 --- a/docs/developer/architecture.rst +++ b/docs/developer/architecture.rst @@ -66,3 +66,9 @@ VTK-to-USD boundary. The installed CLI commands are thin wrappers around these workflow classes. They are the best executable references for supported API usage. + +See Also +======== + +* :doc:`extending` +* :doc:`migration_next` diff --git a/docs/developer/extending.rst b/docs/developer/extending.rst index 3d386417..b43a9cdf 100644 --- a/docs/developer/extending.rst +++ b/docs/developer/extending.rst @@ -84,3 +84,4 @@ See Also * :doc:`architecture` * :doc:`workflows` * :doc:`utilities` +* :doc:`migration_next` diff --git a/docs/developer/migration_next.md b/docs/developer/migration_next.md new file mode 100644 index 00000000..ed2df8a7 --- /dev/null +++ b/docs/developer/migration_next.md @@ -0,0 +1,41 @@ +# Migration Guide — Unreleased + +Breaking changes committed since the last release, and how to update code that +depends on them. + +PhysioTwin4D prefers compatibility: public APIs are broken only when the change +is generally beneficial to future users. When a break is unavoidable, the +project does **not** ship deprecation shims or removed-symbol stubs. Instead, +substantial changes ship with code that automates the conversion, and every +break is recorded here in the commit that introduces it. + +At release time this file is renamed `migration_.md` and a fresh +`migration_next.md` is started for the next cycle. + +_No breaking changes recorded since 2026.08.0._ + +## Entry template + +Append one section per breaking change, newest last, using this shape: + +````markdown +## — + +**Change:** what moved, was renamed, or changed signature. + +**Why:** the benefit to future users that justified the break. + +**Before** + +```python +old_call(argument) +``` + +**After** + +```python +new_call(argument, required_option="value") +``` + +**Automated conversion:** ``, or `None needed`. +```` diff --git a/docs/index.rst b/docs/index.rst index bff37c0f..d6b1b6f0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -211,6 +211,7 @@ close every section. :maxdepth: 2 :caption: Developer Guides :hidden: + :glob: developer/architecture developer/extending @@ -223,6 +224,7 @@ close every section. developer/usd_generation developer/utilities developer/ai_assistants + developer/migration_* .. toctree:: :maxdepth: 1 diff --git a/utils/ai_agent_github_reviews.py b/utils/ai_agent_github_reviews.py index 2d3d530d..e8a90751 100644 --- a/utils/ai_agent_github_reviews.py +++ b/utils/ai_agent_github_reviews.py @@ -646,7 +646,8 @@ def build_prompt( Rejection triggers (from {guidance_names} — treat these as hard rules): - Introduces `X | None` instead of `Optional[X]` (ruff UP007 is suppressed) - - Adds backward-compat shims, re-exports, or removed-symbol stubs + - Adds a deprecation shim, re-export, or removed-symbol stub instead of + a `docs/developer/migration_next.md` entry plus a conversion script - Adds error handling for internal states that cannot happen - In classes that inherit from `PhysioTwin4DBase`, uses `print()` instead of `self.log_info()` / `self.log_debug()` From ea274872496d77b23491ea686f01a105fb7c761d Mon Sep 17 00:00:00 2001 From: Stephen Aylward Date: Wed, 26 Aug 2026 10:12:04 -0400 Subject: [PATCH 2/2] DOC: Align backward-compatibility guidance across agent instruction files The policy landed inconsistently across the files that state it: - check-conventions and the PR-review rejection triggers demanded a conversion script for every public API break, while CLAUDE.md and AGENTS.md already allowed a migration entry to record "None needed". Both now require a script only when the break is substantial. - AGENTS.md, CLAUDE.md, impl, and project-standards prohibited "deprecation shims or removed-symbol re-exports"; the review triggers also named removed-symbol stubs. All five now use the same phrasing. - The release snippet in contributing.rst put migration_.md inside a bash code block, where the angle brackets are redirection operators. Both documented sites now derive a quoted $VERSION from bumpver show. --- .agents/skills/check-conventions/SKILL.md | 10 ++++++---- .agents/skills/impl/SKILL.md | 5 +++-- .cursor/rules/project-standards.mdc2 | 16 +++++++++++----- AGENTS.md | 12 ++++++------ CLAUDE.md | 5 +++-- docs/contributing.rst | 5 +++-- utils/ai_agent_github_reviews.py | 6 ++++-- 7 files changed, 36 insertions(+), 23 deletions(-) diff --git a/.agents/skills/check-conventions/SKILL.md b/.agents/skills/check-conventions/SKILL.md index b3cac592..c3d56ff3 100644 --- a/.agents/skills/check-conventions/SKILL.md +++ b/.agents/skills/check-conventions/SKILL.md @@ -63,12 +63,14 @@ context such as class inheritance), then flag every occurrence of: `CLAUDE.md` may be documented. ### Migration guide -- [ ] A deprecation shim, alias, or re-export kept solely for backward - compatibility. Break the API instead, and provide a conversion script. +- [ ] A deprecation shim, removed-symbol re-export, or removed-symbol stub + kept solely for backward compatibility. Break the API instead, and ship + a conversion script when the break is substantial. - [ ] A public class, method, CLI flag, or signature that the diff renames, removes, or changes, with no matching entry in - `docs/developer/migration_next.md`. Report the missing entry against the - changed line. + `docs/developer/migration_next.md`. The entry may record `None needed` + for the conversion script when the break is not substantial. Report the + missing entry against the changed line. ## Output diff --git a/.agents/skills/impl/SKILL.md b/.agents/skills/impl/SKILL.md index 67969a67..f2edac75 100644 --- a/.agents/skills/impl/SKILL.md +++ b/.agents/skills/impl/SKILL.md @@ -14,8 +14,9 @@ Instructions: 5. Update docstrings and type hints for every changed public method. 6. Run `ruff check . --fix && ruff format .` after editing Python files. 7. Prefer compatibility. Break a public API only when the change is generally - beneficial to future users, and never via a deprecation shim — provide a - conversion script when the change is substantial. + beneficial to future users, and never via a deprecation shim, removed-symbol + re-export, or removed-symbol stub — provide a conversion script when the + change is substantial. 8. Explicitly note any breaking changes introduced, and append an entry for each to `docs/developer/migration_next.md` using the template at the bottom of that file. diff --git a/.cursor/rules/project-standards.mdc2 b/.cursor/rules/project-standards.mdc2 index 83c496bb..598b6624 100644 --- a/.cursor/rules/project-standards.mdc2 +++ b/.cursor/rules/project-standards.mdc2 @@ -49,14 +49,20 @@ git mv old_name.py new_name.py **Prefer compatibility.** Break a public API only when the change is generally beneficial to future users: -- Do not add deprecation shims or removed-symbol re-exports +- Do not add deprecation shims, removed-symbol re-exports, or removed-symbol + stubs - When a break is substantial, ship code that automates the conversion instead - Every commit that breaks a public API adds an entry to `docs/developer/migration_next.md` in that same commit — what changed, why it - benefits future users, before/after code, and the conversion script -- At release: `git mv docs/developer/migration_next.md - docs/developer/migration_.md`, retitle it, and start a fresh - `migration_next.md` from its entry template + benefits future users, before/after code, and the conversion script (or + `None needed` when the break is not substantial) +- At release, archive the guide under the new version and start a fresh one: + +```bash +VERSION=$(bumpver show --no-fetch | sed -n "s/^Current Version: //p") +git mv docs/developer/migration_next.md "docs/developer/migration_$VERSION.md" +# Retitle the archived file, then recreate migration_next.md from its template +``` ## Code Style diff --git a/AGENTS.md b/AGENTS.md index 38d16bce..464240da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,9 +102,9 @@ Version bumping: `bumpver update --patch`, `--minor`, or `--major`. ## Migration Guide PhysioTwin4D prefers compatibility. Break a public API only when the change is -generally beneficial to future users. Never add deprecation shims or -removed-symbol re-exports; when a break is substantial, ship code that -automates the conversion instead. +generally beneficial to future users. Never add deprecation shims, +removed-symbol re-exports, or removed-symbol stubs; when a break is +substantial, ship code that automates the conversion instead. At commit time: if the diff breaks a public API, append an entry to `docs/developer/migration_next.md` in that same commit — what changed, why it @@ -216,9 +216,9 @@ graphify update . # refresh after code changes (AST-only, no API c changes. - Keep diffs small and reviewable. - Prefer editing existing modules over creating new ones. -- No deprecation shims or removed-symbol re-exports. Change the code, log the - break in `docs/developer/migration_next.md`, and provide a conversion script - when the change is substantial. +- No deprecation shims, removed-symbol re-exports, or removed-symbol stubs. + Change the code, log the break in `docs/developer/migration_next.md`, and + provide a conversion script when the change is substantial. ## Testing Role diff --git a/CLAUDE.md b/CLAUDE.md index f8a307bd..8da63519 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,8 +73,9 @@ Strong success criteria let you loop independently. Weak criteria - Prefer compatibility. Break a public API only when the change is generally beneficial to future users. -- Never add deprecation shims or removed-symbol re-exports. When a break is - substantial, ship code that automates the conversion instead. +- Never add deprecation shims, removed-symbol re-exports, or removed-symbol + stubs. When a break is substantial, ship code that automates the conversion + instead. - Every commit that breaks a public API must add an entry to `docs/developer/migration_next.md`: what changed, why it benefits future users, before/after code, and the conversion script (or `None needed`). diff --git a/docs/contributing.rst b/docs/contributing.rst index ddc5de2b..6fa023fb 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -434,8 +434,9 @@ Maintainers only: bumpver update --patch # Archive the migration guide under the new version, then start a fresh one - git mv docs/developer/migration_next.md docs/developer/migration_.md - # Retitle the archived file to "Migration Guide - " + VERSION=$(bumpver show --no-fetch | sed -n "s/^Current Version: //p") + git mv docs/developer/migration_next.md "docs/developer/migration_$VERSION.md" + # Retitle the archived file to "Migration Guide - $VERSION" # Recreate docs/developer/migration_next.md from its entry template # Build package diff --git a/utils/ai_agent_github_reviews.py b/utils/ai_agent_github_reviews.py index e8a90751..0d01f153 100644 --- a/utils/ai_agent_github_reviews.py +++ b/utils/ai_agent_github_reviews.py @@ -646,8 +646,10 @@ def build_prompt( Rejection triggers (from {guidance_names} — treat these as hard rules): - Introduces `X | None` instead of `Optional[X]` (ruff UP007 is suppressed) - - Adds a deprecation shim, re-export, or removed-symbol stub instead of - a `docs/developer/migration_next.md` entry plus a conversion script + - Adds a deprecation shim, removed-symbol re-export, or removed-symbol + stub instead of a `docs/developer/migration_next.md` entry (that entry + needs a conversion script only when the break is substantial; it may + record `None needed` otherwise) - Adds error handling for internal states that cannot happen - In classes that inherit from `PhysioTwin4DBase`, uses `print()` instead of `self.log_info()` / `self.log_debug()`