upstream-fix-and-pin

name	upstream-fix-and-pin
description	自分の依存ライブラリにバグや欠けている機能があり、上流に PR を出して取り込まれるまで下流プロジェクトを動かしたいときの運用。git ref pin（branch HEAD SHA → merge SHA）、`link:` への退避判断、SHA 取り扱い、pnpm v10 の build script gating まで含む。

Upstream Fix and Pin

When to use

依存ライブラリの修正が必要で、その修正が下流プロジェクトの実装やデバッグに必要なとき。具体的には:

• 自分（または同じ org）が owner の OSS で、PR を自分で投げられる
• 修正が merge されるまで、下流が止まると困る
• monkey-patch / fork publish / vendor 相当の重い手段を取る前に試したい

The flow

[1] 上流に branch を切って fix
        │
        ▼
[2] push して PR
        │
        ▼  下流は (3) で繋ぐ
[3] 下流 package.json を git ref で pin (branch HEAD SHA)
        │
        ▼
[4] PR が merge されたら main の merge SHA に張り替え
        │
        ▼
[5] (任意) 上流が npm publish するならそれに乗り換え

PR が長期化したら link: に退避（後述）。

Pin syntax

pnpm / npm 共通:

{
  "dependencies": {
    "<pkg>": "github:<owner>/<repo>#<full-40-char-sha>"
  }
}

ブランチ名 pin (#fix/foo) は便利だが、merge / rebase で SHA が動くので 再現性が無い。lab / 検証用なら full SHA 一択。

SHA を取得する

GitHub の codeload は full 40-char SHA を要求する。短縮 SHA を渡すと:

ERR_PNPM_FETCH_404  GET https://codeload.github.com/<owner>/<repo>/tar.gz/<short>: Not Found - 404

打ち間違いも同じエラーで来る。確実に取るには:

# upstream の clone から
git -C ~/ghq/github.com/<owner>/<repo> rev-parse <branch>


git ls-remote https://github.com/<owner>/<repo> <branch>