Sphinx-Needs renamed the configuration this extension is named after:
needs_extra_options is now needs_fields, and needs_extra_links is now
needs_links (the latter warns: Config option "needs_extra_links" is
deprecated. Please use "needs_links" instead.). The registration API moved
the same way, add_extra_option → add_field, which this extension already
follows (test_reports.py picks add_field on Sphinx-Needs >= 8.5).
The configuration this extension exposes still says "extra option" — about
139 occurrences across 22 files. Worth aligning before the move into the
Sphinx-Needs workspace, so the two do not disagree in the same repository.
Only "extra option" carries the retired word. --link-property,
link_properties and tr_property_link_types map an XML property onto a
link field and are not Sphinx-Needs' needs_extra_links config, so those
names can stay; the docs already say "link field".
Inventory, by release status
Released — renaming breaks existing conf.py files:
Unreleased, part of the CLI work in useblocks/sphinx-test-reports#148 — free to rename:
- the
--extra-option NAME flag
- the
extra_options key of [test_reports] in ubproject.toml (a bridge
key, so it is named after the tr_* value and cannot move alone without
breaking that convention)
extra_options= on build_need, build_needs_file and
case_needs_schema
Options
- Full rename with deprecated aliases.
tr_fields, [test_reports] fields, --field; the old spellings keep working and warn once. Coherent
vocabulary, nobody's conf.py breaks. Largest diff, and it needs the
deprecation path plus a changelog note.
- Unreleased surface only. The flag, the TOML keys and the converter API
get the new names; tr_extra_options stays. Smallest diff, no deprecation
machinery — but then the bridge key and the conf.py value spell the same
setting differently, which is exactly what BRIDGE_KEYS exists to avoid.
- Full rename, no aliases. Cleanest code, breaks existing
conf.py
files. Defensible only if the release is billed as breaking.
One wrinkle
build_need(fields=...) is already taken: it is the map of renameable field
names (file_option, source_file_option, source_line_option). So
extra_options= cannot simply become fields=. One of the two has to give —
the property list as property_fields=, or the map as field_names=.
Where the work lands
fields.py, projectconfig.py (BRIDGE_KEYS, CONVERSION_KEYS), cli.py,
test_reports.py, directives/test_common.py (collect_extra_options),
directives/test_case.py and directives/test_suite.py (allowed_extras),
docs/configuration.rst, docs/cli.rst, the directive docs, and the tests.
The field declarations were centralised in fields.py in useblocks/sphinx-test-reports#148, so the
type-and-description side is a single table now rather than scattered calls.
Raised from a review comment on useblocks/sphinx-test-reports#148:
useblocks/sphinx-test-reports#148 (comment)
Sphinx-Needs renamed the configuration this extension is named after:
needs_extra_optionsis nowneeds_fields, andneeds_extra_linksis nowneeds_links(the latter warns: Config option "needs_extra_links" isdeprecated. Please use "needs_links" instead.). The registration API moved
the same way,
add_extra_option→add_field, which this extension alreadyfollows (
test_reports.pypicksadd_fieldon Sphinx-Needs >= 8.5).The configuration this extension exposes still says "extra option" — about
139 occurrences across 22 files. Worth aligning before the move into the
Sphinx-Needs workspace, so the two do not disagree in the same repository.
Only "extra option" carries the retired word.
--link-property,link_propertiesandtr_property_link_typesmap an XML property onto alink field and are not Sphinx-Needs'
needs_extra_linksconfig, so thosenames can stay; the docs already say "link field".
Inventory, by release status
Released — renaming breaks existing
conf.pyfiles:tr_extra_options(1.2.0)Unreleased, part of the CLI work in useblocks/sphinx-test-reports#148 — free to rename:
--extra-option NAMEflagextra_optionskey of[test_reports]inubproject.toml(a bridgekey, so it is named after the
tr_*value and cannot move alone withoutbreaking that convention)
extra_options=onbuild_need,build_needs_fileandcase_needs_schemaOptions
tr_fields,[test_reports] fields,--field; the old spellings keep working and warn once. Coherentvocabulary, nobody's
conf.pybreaks. Largest diff, and it needs thedeprecation path plus a changelog note.
get the new names;
tr_extra_optionsstays. Smallest diff, no deprecationmachinery — but then the bridge key and the
conf.pyvalue spell the samesetting differently, which is exactly what
BRIDGE_KEYSexists to avoid.conf.pyfiles. Defensible only if the release is billed as breaking.
One wrinkle
build_need(fields=...)is already taken: it is the map of renameable fieldnames (
file_option,source_file_option,source_line_option). Soextra_options=cannot simply becomefields=. One of the two has to give —the property list as
property_fields=, or the map asfield_names=.Where the work lands
fields.py,projectconfig.py(BRIDGE_KEYS,CONVERSION_KEYS),cli.py,test_reports.py,directives/test_common.py(collect_extra_options),directives/test_case.pyanddirectives/test_suite.py(allowed_extras),docs/configuration.rst,docs/cli.rst, the directive docs, and the tests.The field declarations were centralised in
fields.pyin useblocks/sphinx-test-reports#148, so thetype-and-description side is a single table now rather than scattered calls.
Raised from a review comment on useblocks/sphinx-test-reports#148:
useblocks/sphinx-test-reports#148 (comment)