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.