cleanup: evict old low-level public Lua APIs after migration #395

New issue

Closed

opened 2026-04-25 16:20:55 +00:00 by barrettruth · 1 comment

barrettruth commented

2026-04-25 16:20:55 +00:00

Part of #389.
Depends on #393 and #394.
Suggested order: 6.

Problem

Even after a better current-ref model exists, the old promoted Lua surface will continue to pull users toward lower-level helpers and split targeting concepts unless it is explicitly demoted or removed.

Proposed solution

Do the breaking cleanup after the new API and docs have settled:

remove or demote old publicly promoted low-level helpers from the canonical surface
keep only the intended long-term top-level API names in docs and examples
delete compatibility shims if they are no longer needed

This should include reviewing helpers such as the currently promoted forge.ops PR/CI/browse verbs and deciding whether they remain internal, compatibility-only, or are removed outright.

Scope

final API removals / demotions
doc and example cleanup for the removed names
tests adjusted to the final public surface

Acceptance criteria

the documented public Lua API no longer points users at obsolete low-level helpers for common workflows
any removed helper names are fully evicted from canonical docs and examples
the final public naming scheme is internally consistent with the Ex surface

Out of scope

introducing new command semantics

Part of #389. Depends on #393 and #394. Suggested order: 6. ## Problem Even after a better current-ref model exists, the old promoted Lua surface will continue to pull users toward lower-level helpers and split targeting concepts unless it is explicitly demoted or removed. ## Proposed solution Do the breaking cleanup after the new API and docs have settled: - remove or demote old publicly promoted low-level helpers from the canonical surface - keep only the intended long-term top-level API names in docs and examples - delete compatibility shims if they are no longer needed This should include reviewing helpers such as the currently promoted `forge.ops` PR/CI/browse verbs and deciding whether they remain internal, compatibility-only, or are removed outright. ## Scope - final API removals / demotions - doc and example cleanup for the removed names - tests adjusted to the final public surface ## Acceptance criteria - the documented public Lua API no longer points users at obsolete low-level helpers for common workflows - any removed helper names are fully evicted from canonical docs and examples - the final public naming scheme is internally consistent with the Ex surface ## Out of scope - introducing new command semantics

barrettruth commented

2026-04-25 18:47:48 +00:00

Fixed by #403.