Skip to content

PATTERN Cited by 1 source

Upstream collaboration as migration unblock

Summary

When a migration or platform-level infrastructure project hits the ceiling of what can be accomplished outside the core tool — because the remaining problems require access to information or extension points the tool doesn't expose — invest directly in upstream contribution and collaboration to add those extension points. The pattern treats the upstream tool not as a black box to work around but as a collaborator whose seams can be extended. Typical additions: client hooks, event callbacks, API points, bugfixes for failure modes the organisation has characterised.

Why this wins for long-tail problems

Any migration or long-running transformation reveals two classes of problem:

  1. Expressible as custom steps outside the tool. The large majority. Handled by pipeline- with-open-ended-passes.
  2. Not expressible outside the tool. Requires access to the tool's internal symbol resolution, AST manipulation, or execution ordering. Stuck behind the tool's public API.

The latter class typically does not yield to "more custom steps". No external pipeline can substitute for the tool's type-resolving engine, compiler, or staged- transformation state. The only paths forward are:

  • Fork the tool. Expensive, divergence-creating, and incurs a maintenance tax forever.
  • Re-implement functionality externally. Also expensive; also unlikely to match the tool's quality.
  • Collaborate upstream to add the needed hooks. Low marginal cost (hook + extension points are small); the organisation's problems now dissolve into properly-sanctioned plugin steps; the hooks benefit everyone.

Canonical wiki instance — Meta × JetBrains J2K hooks

In early 2024, JetBrains began adapting J2K to the new K2 Kotlin compiler. Meta used the opening to co-invest:

"We took the opportunity to work with JetBrains to improve J2K and address problems that had been plaguing us for years, such as disappearing override keywords. Collaborating with JetBrains also gave us the opportunity to insert hooks into J2K that would allow clients like Meta to run their own custom steps directly in the IDE before and after conversion." (Meta, 2024-12-18.)

Two named benefits Meta called out explicitly:

  1. Improved symbol resolution. Meta's own PSI-based symbol resolution is "less precise than J2K's, especially when it comes to resolving symbols defined in third-party libraries." Porting custom preprocessing / postprocessing to run inside J2K via the new hooks gives Meta's steps access to J2K's more sophisticated static-analysis tooling.
  2. Easier open-sourcing. Some of Meta's Android- specific postprocessing steps "might still be useful to other companies", but their dependency on Meta's private metaprogramming tool ( PSI-based Editus) blocked open-sourcing. Porting to J2K's extension points decouples them from Meta- internal symbol resolution — they become donatable to the open-source community (targeted for contribution via the existing kotlin_ast_ tools repo).

Relationship to patterns/upstream-the-fix

upstream-the-fix is the downstream-consumer pattern: an organisation patches its local fork of OSS and then pushes those specific patches upstream so the fork can eventually retire. upstream-collaboration-as-migration- unblock is the mutual-extension variant: the organisation and the upstream maintainer design new extension points together so the organisation's long- term migration can live inside the upstream tool, not alongside it. Both patterns share the strategic posture — "don't carry a fork" — and in Meta's 2026 engineering writing they appear frequently paired (see Meta FFmpeg, WebRTC fork retirement, jemalloc stewardship reset).

Pattern preconditions

  • The upstream maintainer is active and responsive. J2K had been "complex and not actively developed" for years; Meta explicitly says the K2 porting effort "changed" the situation — upstream activity was a necessary condition.
  • The organisation's requirements generalise. Hooks should serve more than one client; if Meta's proposed hook is Meta-only, upstream has no reason to take it.
  • Organisational willingness to contribute over time. Upstream collaboration is an ongoing investment, not a one-shot patch.

Seen in

Last updated · 550 distilled / 1,221 read