Upstream PR

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.