Skip to content

Upstream-dependency workarounds have no shared convention #459

Description

@IgorShevchik

What

.sync/PORTING.md is a good system for one thing — divergence from nuxt/ui, the fork's parent. It says nothing about the other kind of long-lived exception: code that works around a bug in a dependency we merely consume.

Those exist and each is arranged differently:

Site Upstream bug Tag b24ui issue Test
src/runtime/composables/useBlurOnOpen.ts and its 3 consumers unovue/reka-ui#1280 reka-ui#1280 #159 yes, incl. a tripwire that fires when upstream fixes it
InputMenu.vue, SelectMenu.vue, CommandPalette.vue unovue/reka-ui#1885 (virtualization flattens groups) none none none
src/runtime/utils/overlay.ts scrollbar-click closes the overlay none none none

The first row only looks like that because #159 and #458 happened to work on it.

Why it matters

The third row is the one to look at: it carries a FIXME that says the workaround does not work on macOS. That is a known, shipped, platform-specific defect with no issue tracking it, no test, and nothing that would surface it to anyone who did not open that file.

The second row is the ordinary failure mode: when reka-ui eventually fixes #1885, nothing tells us. The workaround stays forever, and the next person to read it cannot tell whether it is still needed without re-deriving the whole thing.

Suggested scope

A convention, not tooling:

  • every workaround for a dependency bug gets a b24ui issue and is tagged <dep>#<issue> at every site, so grep -rn '<dep>#<issue>' src/ test/ returns the full set — the removal instructions in Track: remove useBlurOnOpen workaround after reka-ui#1280 is fixed #159 relied on exactly this and found nothing until test(Modal): make the reka-ui#1280 removal trigger itself #458;
  • where the upstream condition is cheaply observable, add a tripwire spec that fails when it changes. test/utils/blur-on-open-workaround.spec.ts is the worked example, including the part worth copying: not-found is not a pass, and the failure message says the failure is good news;
  • write the convention down where a porter will meet it — a short section in .sync/PORTING.md or a sibling file.

Then retro-fit the two untracked rows: file an issue for the overlay.ts macOS gap (it deserves one on its own merits), and tag the reka-ui#1885 sites.

Deliberately not proposing a registry file or a script. Three workarounds do not need infrastructure; they need a rule and two tags.

Context

Raised during the review of #458, which found that #159's own documented search returned zero results.

Priority: P3.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions