Tier 3 — documentation vs signal choice
`Vis.source_id` is described in `docs/migration/v2-to-v3.md` and
`CHANGELOG.md` as "deprecated" (one term) and "read-only convenience"
(another term). The setter raises `AttributeError`, so writing to it is
the hard-break signal. But the getter reads silently — no
`DeprecationWarning` fires — even though the CHANGELOG says it's
deprecated.
Pick a word
Option A — emit `DeprecationWarning` on getter. One release of
soft-deprecation signal for anyone reading `vis.source_id`, then remove
in 4.0.
Option B — stop calling it "deprecated". Call it what it is: a
read-only compatibility accessor for logs/tests, not deprecated. Update
CHANGELOG wording to "retained read-only".
Recommendation
(B). py-mat's stated stance is "break cleanly, no deprecation
cycle." If `source_id` were truly deprecated we'd delete it. We kept
it because it's a useful lossless log format (`"ambientcg/Metal012"`
is one line). Stop calling it deprecated; call it a convenience
accessor.
Fix scope
Update phrasing in:
- `CHANGELOG.md` `[3.1.0]` → remove "deprecated" for `source_id`
- `docs/migration/v2-to-v3.md` → same
- `src/pymat/vis/_model.py` property docstring
No code change.
Labels
`question` because this is a documentation-language call, not a
behavior change. Re-label `documentation` if ready to commit to
option (B).
Tier 3 — documentation vs signal choice
`Vis.source_id` is described in `docs/migration/v2-to-v3.md` and
`CHANGELOG.md` as "deprecated" (one term) and "read-only convenience"
(another term). The setter raises `AttributeError`, so writing to it is
the hard-break signal. But the getter reads silently — no
`DeprecationWarning` fires — even though the CHANGELOG says it's
deprecated.
Pick a word
Option A — emit `DeprecationWarning` on getter. One release of
soft-deprecation signal for anyone reading `vis.source_id`, then remove
in 4.0.
Option B — stop calling it "deprecated". Call it what it is: a
read-only compatibility accessor for logs/tests, not deprecated. Update
CHANGELOG wording to "retained read-only".
Recommendation
(B). py-mat's stated stance is "break cleanly, no deprecation
cycle." If `source_id` were truly deprecated we'd delete it. We kept
it because it's a useful lossless log format (`"ambientcg/Metal012"`
is one line). Stop calling it deprecated; call it a convenience
accessor.
Fix scope
Update phrasing in:
No code change.
Labels
`question` because this is a documentation-language call, not a
behavior change. Re-label `documentation` if ready to commit to
option (B).