Summary
AGENTS.md requires en-GB-oxendict (-ize / -yse / -our) spelling, but scopes the rule to comments:
Use consistent spelling and grammar. Comments must use en-GB-oxendict ("-ize" / "-yse" / "-our") spelling and grammar, with the exception of references to external APIs. Markdown prose is enforced mechanically by the pinned typos spelling gate in make lint and make markdownlint.
— AGENTS.md:18-21
Code identifiers are therefore governed by nothing, and have drifted to -ise. This needs a decision and, if the rule is extended, a code change — hence a separate issue rather than an inline fix.
Why it isn't caught today
The spelling target only feeds Markdown to typos:
spelling: spelling-helper-test ## Enforce en-GB-oxendict spelling in Markdown prose
@$(UV_RUN_ENV) uv run scripts/generate_typos_config.py
@git ls-files -z '*.md' | \
xargs -0 -r $(TYPOS) --config typos.toml --force-exclude
No Python or Rust source reaches the gate, so identifier spelling can drift indefinitely without any check failing.
Current inventory (origin/main)
Twelve distinct -ise identifiers, found by walking the AST for definitions, assignment targets, and arguments (so comments and docstrings are excluded):
| Identifier |
Location |
normalised (local var, ×4) |
cuprum/_backend.py:72, cuprum/unittests/test_args_validators_property.py:101, cuprum/unittests/test_backend_resolver_property.py:109, +1 |
_normalise_wheel_entry |
tests/helpers/maturin.py |
_normalise_line_endings |
cuprum/unittests/test_line_splitting.py:142 |
_rebuild_normalised_text |
cuprum/unittests/test_line_splitting.py:147 |
_split_preserves_normalised_text |
cuprum/unittests/test_line_splitting.py:163 |
_summarise_folded |
cuprum/unittests/test_folded_summary.py:23 |
test_keyword_arguments_are_serialised_to_flags |
cuprum/unittests/test_sh.py:46 |
test_keyword_arguments_normalise_underscores |
cuprum/unittests/test_sh.py:59 |
test_build_argv_orders_and_normalises |
cuprum/unittests/test_sh_property_based.py:68 |
The Rust crate has no -ise identifiers, so this is Python-only.
Every one is private (leading underscore), test-local, or a local variable — none appears in any __all__ and none is public API. A rename is therefore an internal change with no consumer impact and no deprecation shim required.
Decision required
Pick one:
- Extend the rule to identifiers. Rename the twelve above to
-ize, and update AGENTS.md to say identifiers are in scope. Consistent with the prose rule; costs one mechanical PR.
- Scope the rule explicitly to prose. Leave identifiers alone and amend AGENTS.md to state that names are exempt, so the current state stops reading as an oversight and future reviews stop raising it.
Either way the wording in AGENTS.md should become explicit, because today the ambiguity is what generates the review churn.
Suggested resolution if option 1
- Rename the twelve identifiers (mechanical;
leta can drive the rename so references stay consistent).
- Extend the spelling gate to source files so it cannot drift again, e.g. add
*.py/*.rs to the spelling target. This needs care: typos will also inspect string literals and comments, so expect an initial pass to surface unrelated findings and to need typos.toml exclusions for genuine external-API references (serialize in third-party call sites, normalize in unicodedata, and similar).
- Update AGENTS.md to describe the widened scope.
Context
Raised from a CodeRabbit finding on #240, which asked for -ize in the changed docstrings. The docstrings were fixed there; the identifiers were deliberately left alone and the reasoning recorded on the thread, because renaming them would have made that one module inconsistent with its neighbours without the rule requiring it.
Summary
AGENTS.md requires en-GB-oxendict (
-ize/-yse/-our) spelling, but scopes the rule to comments:Code identifiers are therefore governed by nothing, and have drifted to
-ise. This needs a decision and, if the rule is extended, a code change — hence a separate issue rather than an inline fix.Why it isn't caught today
The
spellingtarget only feeds Markdown totypos:No Python or Rust source reaches the gate, so identifier spelling can drift indefinitely without any check failing.
Current inventory (
origin/main)Twelve distinct
-iseidentifiers, found by walking the AST for definitions, assignment targets, and arguments (so comments and docstrings are excluded):normalised(local var, ×4)cuprum/_backend.py:72,cuprum/unittests/test_args_validators_property.py:101,cuprum/unittests/test_backend_resolver_property.py:109, +1_normalise_wheel_entrytests/helpers/maturin.py_normalise_line_endingscuprum/unittests/test_line_splitting.py:142_rebuild_normalised_textcuprum/unittests/test_line_splitting.py:147_split_preserves_normalised_textcuprum/unittests/test_line_splitting.py:163_summarise_foldedcuprum/unittests/test_folded_summary.py:23test_keyword_arguments_are_serialised_to_flagscuprum/unittests/test_sh.py:46test_keyword_arguments_normalise_underscorescuprum/unittests/test_sh.py:59test_build_argv_orders_and_normalisescuprum/unittests/test_sh_property_based.py:68The Rust crate has no
-iseidentifiers, so this is Python-only.Every one is private (leading underscore), test-local, or a local variable — none appears in any
__all__and none is public API. A rename is therefore an internal change with no consumer impact and no deprecation shim required.Decision required
Pick one:
-ize, and update AGENTS.md to say identifiers are in scope. Consistent with the prose rule; costs one mechanical PR.Either way the wording in AGENTS.md should become explicit, because today the ambiguity is what generates the review churn.
Suggested resolution if option 1
letacan drive the rename so references stay consistent).*.py/*.rsto thespellingtarget. This needs care:typoswill also inspect string literals and comments, so expect an initial pass to surface unrelated findings and to needtypos.tomlexclusions for genuine external-API references (serializein third-party call sites,normalizeinunicodedata, and similar).Context
Raised from a CodeRabbit finding on #240, which asked for
-izein the changed docstrings. The docstrings were fixed there; the identifiers were deliberately left alone and the reasoning recorded on the thread, because renaming them would have made that one module inconsistent with its neighbours without the rule requiring it.