Index of every page on this site: llms.txt
All skills
pulumi avatar

/upstream-patches

@cd1011f official
by pulumipulumi/agent-skills80 stars
8
Run it yourself

Create, amend, remove, and rebase patches for Terraform provider submodules using `./scripts/upstream.sh`. Use when `upgrade-provider` or manual patch work needs owning-patch lookup, patch conflict fixes, patch/hunk removal, or upstream rebase.

Use this Skill: https://skilld.dev/gh/pulumi/agent-skills/upstream-patches

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈66 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈199 more on demand in 2 files.

Description uses 3.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈263 characters, or 3.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Upstream Patches

upstream/ is a git submodule pointing to the upstream Terraform provider. patches/ contains patch files applied on top of it. Use ./scripts/upstream.sh to manage patch state.

Default Behavior

  • If fixing a regression introduced by an existing patch, amend the owning patch commit.
  • Do not create a new patch unless the user explicitly asks.

Commands Reference

Command Description
./scripts/upstream.sh init Initialize upstream and apply patches to working directory
./scripts/upstream.sh init -f Destructively discard checkout/rebase state and re-initialize upstream
./scripts/upstream.sh checkout Create branch with patches as commits for editing
./scripts/upstream.sh rebase -i Interactively edit patch commits
./scripts/upstream.sh rebase -o <commit> Rebase patches onto a new upstream commit
./scripts/upstream.sh check_in Write commits back to patches and exit checkout mode

Guardrails

  • Never commit directly to upstream/ without checkout/check_in.
  • Direct edits under upstream/ outside checkout are ephemeral during upgrade-provider; the tool resets submodule state.
  • Do not hand-edit patches/*.patch unless intentionally doing raw patch surgery.
  • Prefer non-interactive rewrite flow over interactive rebase for agents.

Find Owning Patch First

Before editing patch content, identify the owning patch/commit.

./scripts/upstream.sh checkout

# Find candidate patch files by touched file path or unique hunk text
rg -n "path/to/file|unique_symbol" patches/*.patch

# Optional: inspect candidate patch header/hunks
sed -n '1,120p' patches/00NN-Example.patch

# Map patch file to commit in upstream checkout branch
patch=patches/00NN-Example.patch
subject=$(sed -n 's/^Subject: \[PATCH\] //p' "$patch" | head -n1)
cd upstream
git log --oneline pulumi/patch-checkout --grep "$subject"

# If needed, disambiguate by touched path
git log --oneline pulumi/patch-checkout -- path/to/file
cd ..

If rg is unavailable, use grep -En for the patch search. Set target_sha to the owning commit and edit that commit, not HEAD.

Amend Existing Patch (Preferred, Non-Interactive)

./scripts/upstream.sh checkout
cd upstream

target_sha=<owning-commit-sha>
base_sha=$(git rev-parse "${target_sha}^")
tmp_branch="rewrite-${target_sha:0:8}"

# Rebuild history from parent of target commit
git checkout -b "$tmp_branch" "$base_sha"
git cherry-pick "$target_sha"

# Apply fix and amend target commit
# ...edit files...
git add <files>
git commit --amend --no-edit

# Replay remaining commits
git cherry-pick "${target_sha}..pulumi/patch-checkout"

# If cherry-pick conflicts occur:
#   resolve files
#   git add <resolved files>
#   git cherry-pick --continue

# Move checkout branch to rewritten history
git branch -f pulumi/patch-checkout HEAD
git checkout pulumi/patch-checkout
git branch -D "$tmp_branch"
cd ..

Interactive fallback:

./scripts/upstream.sh checkout
./scripts/upstream.sh rebase -i
# mark target commit as edit, amend, then continue

Remove Entire Patch

Use when a patch should be deleted completely.

rm patches/00NN-Description.patch
./scripts/upstream.sh checkout
./scripts/upstream.sh check_in

Remove Part of a Patch

Use when only selected hunks/files should be removed from an existing patch.

  1. Find owning patch/commit (target_sha) and use the amend workflow above.
  2. Revert only unwanted changes from the target commit, then amend.

Example during amend step:

cd upstream
# Restore specific docs-only files from parent of amended commit
git checkout HEAD^ -- path/to/docs-only-file path/to/another-doc-file
git add path/to/docs-only-file path/to/another-doc-file
git commit --amend --no-edit
cd ..

Create New Patch (Only If Requested)

./scripts/upstream.sh checkout
cd upstream
# ...make changes...
git add <files>
git commit -m "Describe new patch"
cd ..
./scripts/upstream.sh check_in

Rebasing Patches to a New Upstream Version

./scripts/upstream.sh checkout

# Rebase onto the new upstream commit
./scripts/upstream.sh rebase -o <new_commit_sha>
# Resolve any conflicts that arise

# Write updated patch files
./scripts/upstream.sh check_in

Verification Checklist

Before check_in:

  • Confirm expected patch count change (0 by default; -1 for full patch removal).
  • Confirm whether target patch should remain present (default yes) or be removed (explicit deletion case).
  • Confirm you are editing the owning commit, not adding a new commit by accident.

After check_in:

  • Verify patch count matches expectation.
  • Verify target patch number/purpose is still present when expected.
  • Verify no unexpected new 00NN-*.patch was introduced.

Interrupted Checkout or Rebase

Preserve work by default. Inspect git -C upstream status, complete the active git am/rebase, verify that every patch was applied, and run ./scripts/upstream.sh check_in before rerunning automation. An interrupted checkout invokes git am separately for each patch, so later patch files may not have been reached.

Use ./scripts/upstream.sh init -f only when intentionally discarding all interrupted work. It can remove conflict resolution, patch commits, operation metadata, and untracked files; it is not routine recovery for a stuck checkout.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides instructions for managing git patches in Terraform provider repositories using a local script and standard git commands. It is evaluated as low risk due to a potential indirect prompt injection surface when reading patch files.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at cd1011f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 4 months ago
  • Git/VCS
  • terraform
  • patches
  • submodules
  • upstream
  • provider
  • rebase
  • patch-management

README badge

README badge for pulumi/agent-skills/upstream-patches

Manages patch files for Terraform provider submodules using `./scripts/upstream.sh`, enabling amendment, removal, rebasing, and conflict resolution without direct git operations on the upstream submodule. Targets workflows where patches need lookup by owning commit, hunk-level editing, or rebasing onto new upstream versions.

Generated from the current SKILL.md.

What is the difference between amending an existing patch and creating a new patch?
Amend an existing patch when fixing a regression introduced by that patch. Only create a new patch if the user explicitly requests it. The skill defaults to amendment to avoid unnecessary patch proliferation.
How do I identify which patch file owns a particular change?
Use `./scripts/upstream.sh checkout`, then search patch files by touched file path or unique hunk text with `rg`. Map the patch file to its commit in the upstream checkout branch by matching the Subject header or by querying git log for touched files.
Can I hand-edit .patch files directly?
No, unless you are intentionally doing raw patch surgery. Use the `checkout/check_in` workflow instead. Direct edits outside checkout mode are ephemeral and will be discarded during upgrade operations.
What should I do if checkout mode gets stuck?
Run `./scripts/upstream.sh init -f` to force re-initialize and reset submodule state.
Does this skill support rebasing patches onto a new upstream version?
Yes. Use `./scripts/upstream.sh checkout`, then `./scripts/upstream.sh rebase -o <new_commit_sha>` to rebase patches and resolve conflicts, followed by `check_in` to write the updated patch files.

Generated from the current SKILL.md. These answers refresh after source changes.