upstream-pr

Source forks may change core freely. This skill applies only when an upstream contribution is requested; maintaining a local change does not require contributing it. Keep private deployment material in deploy/layers/<org>/ in a private source fork or in a separate private deployment repository for public source. Core means the runtime, plugins, CLI, docs, and CI, and may also contain private details that must be scrubbed.

Upstream qm is shared with organizations other than yours, and anything pushed there is permanent: it stays reachable by SHA in every clone and fork even after a deleted branch or a force-push. Treat a leak as unrecoverable and spend the effort before the push.

See deploy/layers/README.md for the boundary, and the update-qm skill for syncing the other direction.

Where the branch will go

git remote -v, the source tree, and repository metadata identify the situation. This decides the push target only; the scrub steps below run in every case.

• origin is yc-software/qm: you are in upstream qm. Push the branch to origin and open the PR there.
• origin is a GitHub fork of qm, meaning a repository created with GitHub's fork feature and living inside qm's fork network: push to origin and open a normal cross-repo PR.
• A standalone source fork: assume it may hold private material even if deploy/layers/ looks empty, and read "Pushing from a private fork" below.
• A package deployment or unrelated repository: prepare the contribution in a separate clean upstream checkout; never push its history to upstream.

Judge by where origin points, not by the repository's name. A repository named <org>/qm-<something> in the same GitHub organization as the source may still be a separate downstream repository.

Decide whether the change belongs upstream

Ask what the change would mean to an organization that is not yours. It belongs upstream when it is a fix or capability in core qm that any deployment would want. It does not belong upstream when it only makes sense given how your organization is set up: its tools, its vocabulary, its providers, its process. Keep that change downstream: deployment material belongs in the layer or private deployment repository, while source behavior may remain a local core modification.

A change that is generic in substance but written against org-specific fixtures needs its fixtures rewritten first. Model them on the account-neutral fixtures under deploy/stacks/ rather than inventing values from your own deployment.

Start from a clean tree and a clean branch

A branch cut from a private fork's main carries every organization commit in its history, and a PR from it exposes all of them. Cut from upstream instead.

git switch -c carries modified and untracked files onto the new branch, where a later git add -A sweeps them into the PR. So first require a clean tree; this must print nothing:

git status --porcelain

Use upstream below for the verified upstream remote; in an upstream checkout use origin instead throughout these commands and the history checks.

Then:

git fetch upstream
git switch -c <topic> upstream/main
git cherry-pick <sha> [<sha>...]

If the change is entangled with organization commits and will not cherry-pick cleanly, reimplement it on the clean branch. That is faster than auditing a messy history, and it fails safe.

Scrub

Run all four checks against the final branch state, and again after any amend or rebase.

The scans walk every commit rather than the net diff, because two ordinary moves defeat a net diff. Moving a file out of deploy/layers/ with git mv is recorded as a rename, so the diff never shows its contents. Adding a layer file in one commit and deleting it in a later one leaves the net diff empty, but the file still ships in the branch's history. git log -p --no-renames sees both.

Capture the outgoing history once, into the gitignored .generated/:

mkdir -p .generated/upstream-pr
git log -p --no-renames \
  --format='commit %H%nauthor %an <%ae>%ncommitter %cn <%ce>%n%s%n%b' \
  upstream/main..HEAD > .generated/upstream-pr/outgoing.txt

1. No layer paths in any commit.

git log --name-status --no-renames --format='' upstream/main..HEAD \
  | grep -E 'deploy/layers/[^/]+/' || echo "PASS: no layer paths"

On any hit, stop and rebuild the branch. No PR to upstream legitimately touches an organization's layer directory. The shared deploy/layers/README.md is core and may change, which is why the pattern matches only paths inside an organization's subdirectory.

2. No private organization identifiers in content, messages, or authorship. Build the term list from the private deployment and local core changes, wherever they live: qm.config.jsonc has the org slug and public URL host, .env.example has the computed secret names, .env has the secret values, slack-app-manifest.yml has workspace and app names, infra/terraform.tfvars has cloud account and repository coordinates, and sandbox/ has internal tool and system names. Add your email domains, teammates' names, and any customer or partner names.

Authorship is scanned because a clone configured with an internal user.email stamps it on every commit, and it stays visible on the upstream PR.

cat > .generated/upstream-pr/terms.txt <<'TERMS'
acme
acme.example.com
123456789012
TERMS

test -s .generated/upstream-pr/terms.txt || echo "REFUSING: term list is empty"
grep -inFf .generated/upstream-pr/terms.txt .generated/upstream-pr/outgoing.txt \
  || echo "PASS: no identifier hits"

Replace the example terms with real ones. If the placeholders are left in, the grep matches nothing and looks like a pass.

3. Account for every binary. A diff shows a binary as one line with no content, so the identifier scan cannot see inside it. Screenshots, sandbox/tools/<id>/<binary>, state snapshots, and PDFs all land here.

grep '^Binary files' .generated/upstream-pr/outgoing.txt || echo "PASS: no binaries"

Justify each hit individually or drop it from the branch.

4. The surfaces git cannot see. None of these appear in any diff:

• the branch name
• the PR title and description, including pasted error output or stack traces, which routinely carry internal hostnames, account IDs, and real user identifiers
• screenshots attached to the PR. This repository requires one for any change an operator or user sees rendered, and a screenshot of your instance shows your organization's data, channels, and people. Reproduce the surface against synthetic data and say that you did.
• reproduction steps that name an internal system, and test data derived from real records

The title and description also carry no provenance. Write them from upstream's point of view and describe what the change does, never where it came from. That the change originated in a private fork, was cherry-picked from other branches, passed your fork's CI, or was prepared with this skill is process, not content, and naming your fork points readers at a repository they cannot see. Mention private forks only when the fork model itself is the subject of the change.

Pushing from a private fork

A private fork is a standalone repository outside GitHub's fork network, so it cannot open a cross-repo pull request.

If you have write access to upstream qm, push the topic branch there and open the PR inside that repository:

git push upstream <topic>
gh pr create --repo yc-software/qm --base main --head <topic> \
  --title "<title>" --body-file .generated/upstream-pr/body.md

If you do not, keep a separate public GitHub fork of qm for contributions and push the branch there from a different clone. Do not add that GitHub fork as a remote in the private fork's clone, where a mistyped push target would send private history to a public repository.

Always pass --title and --body-file; without them gh prompts, which fails in a non-interactive run. Pass --head explicitly, because gh otherwise infers the head repository from local remotes, and a private fork's origin is the private repository. For the same reason, pass --repo to every gh command you run in a private fork: without it, gh pr edit 1 can silently overwrite PR #1 of the source repository. If that happens, the prior body is recoverable through the GraphQL userContentEdits field.

After the PR merges, bring it downstream through update-qm. Preserve any existing local implementation while reconciling it with the merged version; do not blindly apply the patch again.

If something leaked

Say so immediately rather than quietly force-pushing. A deleted branch or amended commit stays reachable by SHA on GitHub and in every clone. Rotate whatever was exposed (credentials, tokens, URLs that act as capabilities) and tell whoever owns the affected system. The disclosure is the fix; rewriting history is not.