Port Upstream

Port upstream tailwind-merge changes

This gem is a Ruby port of dcastil/tailwind-merge (TypeScript). Upstream fixes — usually to the default config — need to be re-implemented here by hand. This skill turns the user's GitHub notification inbox into a triage report, then ports the approved PRs one at a time.

The single source of truth for "already ported" is a commit-message trailer: every port commit ends with a line like Ports dcastil/tailwind-merge#705. Grep git history for that marker instead of keeping a separate state file — history can't drift out of sync with itself.

Phase 1 — Triage

1. Fetch unread notifications for the upstream repo, keeping the thread id (needed later to mark it read) and the PR number from the subject URL:

   gh api notifications --paginate \
     -q '.[] | select(.repository.full_name == "dcastil/tailwind-merge") | {thread_id: .id, type: .subject.type, title: .subject.title, url: .subject.url}'

   Ignore non-PullRequest subjects (issues, releases) unless the user asks about them. Dedupe if several threads point at the same PR. If the inbox is empty, say so and stop — unless the user asked for a sweep (see below).

2. For each PR number, fetch its state and metadata:

   gh pr view <N> -R dcastil/tailwind-merge --json state,title,url,mergedAt,body,files

   Sort the PRs into three buckets:

   • Not merged yet (OPEN): leave the notification unread and don't track it — porting unmerged work is speculative. Mention these in one summary line so the user knows why they weren't handled.
   • Merged, already ported: check with git log -E --grep 'dcastil/tailwind-merge#<N>([^0-9]|$)' (the character class stops #70 from matching #708). If a commit exists, mark the notification read right away — the inbox should reflect remaining work: gh api --method PATCH /notifications/threads/<thread_id>
   • Merged, not ported: this is the work queue.

3. Present a triage report for the work queue: upstream title, link, merge date, which upstream files it touches, and which Ruby files that maps to (see the translation table). Flag PRs that likely have nothing to port — changes confined to TypeScript types, docs, bundling, CI, or dependency bumps have no Ruby counterpart.

4. Ask the user which PRs to port before writing any code (recommend all the applicable ones). PRs the user decides to skip as not applicable also get their notification marked read — a conscious "no" is handled work.

Phase 2 — Port (one upstream PR at a time)

Port approved PRs oldest merge first — upstream PRs often touch adjacent config lines, so applying them in merge order avoids self-inflicted conflicts. Each port is its own branch off main, its own commit, its own PR here.

For each PR:

1. Start clean: git checkout main && git pull.

2. Branch using the repo's convention: fix/<kebab-summary> (or feat/ if the upstream change adds behavior).

3. Read the full upstream change: gh pr diff <N> -R dcastil/tailwind-merge, plus the PR body — dcastil's descriptions usually explain the CSS-level why, which belongs in the commit message here.

4. Translate the diff using the table and idioms below. Port the upstream test changes too — a port without its tests isn't verified.

5. Run the suite and linter:

   bundle exec rake test && bundle exec rake rubocop

   Fix failures before committing. Do not touch version.rb or CHANGELOG.md — release-please generates both from conventional commits.

6. Commit with a conventional message modeled on git show 66d8e2a: fix(config): <subject>, a body explaining the CSS behavior being fixed (not just "port upstream"), and the trailer as the final line:

   Ports dcastil/tailwind-merge#<N>.

   That trailer is the tracking mechanism — omitting it means the PR shows up as unported forever.

   Commits are signed through 1Password's SSH agent. If git commit fails with 1Password: failed to fill whole buffer, 1Password is locked — ask the user to unlock it and retry (the commit may also need to run outside the sandbox to reach the agent).

7. Push and open a PR against main with gh pr create, linking the upstream PR in the description.

8. Mark the notification thread read: gh api --method PATCH /notifications/threads/<thread_id>

Finish with a summary: PRs opened here (with links), PRs skipped and why, and anything left unread in the inbox (e.g. unmerged upstream PRs).