Deprecation automation is still stamping `@deprecated in 5.1.9` onto APIs first deprecated in later minors

[hl662]

Core team follow-up

The core team will:

1. Fix the auto deprecation script so newly generated deprecation comments stop being stamped with the stale 5.1.9 version.
2. Fix the incorrect existing @deprecated in 5.1.9 comments and pin each one to the actual minor version in which that API was deprecated.

---

Summary

The repo currently contains many @deprecated in 5.1.9 comments that are stale or impossible.

The strongest root-cause hypothesis is that the deprecation automation stopped updating common/config/eslint/eslint.config.deprecation-policy.js, leaving addVersion stuck at 5.1.9, while later automation continued rewriting deprecation comments.

Current inventory from the repo head:

rg -n "@deprecated in 5\.1\.9" core domains presentation editor extensions tools ui utils full-stack-tests common -g '!common/temp/**' -S

Result: 116 current hits

At least some of these are provably impossible as 5.1.9 deprecations because the replacement APIs they reference did not exist in release/5.1.9.

---

Why this looks like an automation regression

• Current policy config still contains addVersion: "5.1.9":
  • common/config/eslint/eslint.config.deprecation-policy.js
• The older pipeline template used to rewrite that value before lint-deprecation:
  • common/config/azure-pipelines/templates/run-eslint-deprecation.yaml
• The likely regression point is 617df2cf8cd (Move Deprecation Date Commit in Version Bump Pipeline (#8470)), where the logic moved into:
  • common/config/azure-pipelines/jobs/version-bump.yaml

The working hypothesis is that the step which updated addVersion was dropped there, while the later lint-deprecation rewrite path kept running.

---

APIs incorrectly tagged as 5.1.9, but actually introduced in later minors

Current bucketing from the repo head:

• 116 current @deprecated in 5.1.9 hits total
• 114 appear to actually belong to 5.9.0
• 2 appear to actually belong to 5.5.0

Actual minor: 5.9.0

PR / change	First deprecation-intro commit	First containing release tag	Current stale 5.1.9 hits	Scope	Representative links
#9127 — explicit editing migration (EditTxn, txn overloads, EditCommand, callback arg renames)	5e6c6884d37e4e1338589c2235a246cad79c6114	release/5.9.0	107	backend editing APIs, linear-referencing helpers, frontend/common EditCommand bridge, callback arg renames	IModelDb.ts, Element.ts#L672, Relationship.ts#L85, LinearReferencingElements.ts#L88, IpcAppProps.ts#L172, BriefcaseConnection.ts#L372
#9140 — ChangesetReader / changeset adaptor modernization	4e55029226	release/5.9.0	7	ChangesetECAdaptor deprecations that now point to ChangesetReader, ChangeMeta, ChangeCache, PartialChangeUnifier, etc.	ChangesetECAdaptor.ts#L357, #L419, #L828

Affected files for 5.9.0 / PR #9127 editing bucket (107 hits across 25 files)

• core/backend/src/IModelDb.ts — 22
• domains/linear-referencing/backend/src/LinearReferencingElements.ts — 10
• core/backend/src/Relationship.ts — 10
• core/backend/src/Element.ts — 10
• core/backend/src/LineStyle.ts — 6
• core/backend/src/ViewDefinition.ts — 6
• core/backend/src/Model.ts — 6
• core/backend/src/ElementTreeWalker.ts — 5
• core/backend/src/Category.ts — 4
• core/backend/src/SheetIndex.ts — 4
• core/backend/src/CodeSpecs.ts — 3
• domains/linear-referencing/backend/src/LinearReferencingElementAspects.ts — 2
• core/common/src/IpcAppProps.ts — 2
• core/frontend/src/BriefcaseConnection.ts — 2
• core/backend/src/DisplayStyle.ts — 2
• core/backend/src/ExternalSource.ts — 2
• core/backend/src/domains/GenericElements.ts — 2
• core/backend/src/internal/ChannelAdmin.ts — 2
• domains/linear-referencing/backend/src/test/LinearReferencingSchema.test.ts — 1
• core/frontend/src/tools/PrimitiveTool.ts — 1
• core/backend/src/Material.ts — 1
• core/backend/src/ElementAspect.ts — 1
• core/backend/src/annotations/ElementDrivesTextAnnotation.ts — 1
• core/backend/src/domains/FunctionalElements.ts — 1
• core/backend/src/Texture.ts — 1

This bucket includes:

• direct EditTxn.* replacement comments
• txn-overload replacements like Element.insert(txn) / Model.insert(txn)
• EditCommand bridge comments in common/frontend
• callback arg rename comments like onRootChangedArg / onBeforeOutputsHandledArg

Affected lines for 5.9.0 / PR #9140 changeset bucket (7 hits)

All 7 current stale comments are in core/backend/src/ChangesetECAdaptor.ts:

• #L357
• #L377
• #L391
• #L419
• #L450
• #L660
• #L828

Actual minor: 5.5.0

PR / change	First deprecation-intro commit	First containing release tag	Current stale 5.1.9 hits	Scope	Representative links
#8521 — geometry deprecation cleanup	cb9f43e23e	release/5.5.0	2	geometry API comments pointing to newer preferred members	Ellipsoid.ts#L550, ClipPrimitive.ts#L428

Affected lines for 5.5.0 geometry bucket

• core/geometry/src/geometry3d/Ellipsoid.ts#L550
  • current stale text points users to sectionArcInPlaneOfInterpolatedNormal
• core/geometry/src/clipping/ClipPrimitive.ts#L428
  • current stale text points users to transformValid

---

Strongest “impossible as 5.1.9” examples

A few examples that are especially hard to reconcile with 5.1.9:

• core/backend/src/IModelDb.ts currently contains deprecations like Use EditTxn.insertAspect/updateAspect/deleteAspect instead, but those EditTxn replacements were introduced by #9127 and first appear in release/5.9.0, not release/5.1.9.
• domains/linear-referencing/backend/src/LinearReferencingElements.ts#L88 points to txn-based replacements that also arrive with #9127.
• core/backend/src/ChangesetECAdaptor.ts#L357 points to ChangesetReader-based replacements introduced by #9140, again not present in release/5.1.9.
• core/geometry/src/geometry3d/Ellipsoid.ts#L550 points to a preferred API introduced by #8521, first present in release/5.5.0.

---

Repro / audit commands

Commands used to audit the current repo state

rg -n "@deprecated in 5\.1\.9" core domains presentation editor extensions tools ui utils full-stack-tests common -g '!common/temp/**' -S

# geometry bucket
git log --reverse -G '@deprecated.*sectionArcInPlaneOfInterpolatedNormal' -- core/geometry/src/geometry3d/Ellipsoid.ts | head -1
git log --reverse -G '@deprecated.*transformValid' -- core/geometry/src/clipping/ClipPrimitive.ts | head -1

# callback arg rename bucket
git log --reverse -G '@deprecated.*onRootChangedArg|@deprecated.*onDeletedDependencyArg' -- core/backend/src/Relationship.ts | head -1
git log --reverse -G '@deprecated.*onBeforeOutputsHandledArg|@deprecated.*onAllInputsHandledArg' -- core/backend/src/Element.ts | head -1

# changeset bucket
git log --reverse -G '@deprecated.*ChangesetReader|@deprecated.*ChangeCache|@deprecated.*ChangeMeta|@deprecated.*PartialChangeUnifier|@deprecated.*DateTime namespace' -- core/backend/src/ChangesetECAdaptor.ts | head -1

# first containing release tag
git tag --contains <commit> | rg '^release/5\.' | sort -V | head -1

---

Expected follow-up

This should split into two fixes:

1. Automation fix

   • make the version-bump deprecation rewrite path update addVersion again before running the rewrite

2. Source fix

   • correct the currently stale @deprecated in 5.1.9 comments to the actual minor version
   • based on the current inventory, that means at least:
     • 5.9.0 for the editing / txn / EditCommand / changeset-reader buckets
     • 5.5.0 for the geometry bucket

If maintainers want, I can follow up with a narrower implementation PR for either:

• the automation fix first, or
• the source-comment cleanup first

— Nambot 🤖