Add PR template + CONTRIBUTING.md for fork-vs-upstream policy#3
Merged
Conversation
quiknode-labs/shredstream-proxy is a fork of jito-labs/shredstream-proxy. Changes here split into two buckets: 1. Generic improvements (bug fixes, features) that should also flow upstream — branch as `feature/*` or unprefixed, optionally PR upstream after merging here. 2. Fork-specific overrides (CI, deploy, infra) that should never go upstream — branch as `qn/*`. This PR introduces: - `.github/PULL_REQUEST_TEMPLATE.md` — checkbox that forces every PR author to consciously declare whether the change is upstreamable. GitHub renders it as the default body when opening a PR. - `CONTRIBUTING.md` — branch naming convention, examples, the right `gh pr create` invocations for each case, and a note on `gh repo sync` for pulling from upstream. The goal is to make accidental upstream contribution of fork-specific code unlikely without resorting to maintaining a separate vendor branch. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Now that `main-qn` exists as the QN-side default branch and `master` is being repositioned as a clean mirror of jito-labs/shredstream-proxy, the policy docs need to reflect the new two-branch model. Changes: - PR template: target text now references `main-qn` (default) vs `master` (upstream mirror). The upstreamable workflow is described as "land on main-qn first, then cherry-pick to master and open upstream PR" — same pattern, just made explicit. - CONTRIBUTING.md: rewritten with a clear two-branch table at the top, branch-naming rules updated to specify branch-off and PR-target separately, full day-to-day workflow for both fork-only and upstreamable changes (with the cherry-pick step spelled out), and a section on `gh repo sync` for refreshing master from upstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds two sections to CONTRIBUTING.md that became relevant after PR #4 (CI fixes) landed and branch protection rulesets were configured: - "What's currently QN-specific" — lists the three categories of changes on main-qn that diverge from upstream: the metric label patch (eligible for upstream), the CI workflow overrides (fork-specific), and the policy docs themselves. Future contributors can use this as a reference for what "broadly useful" looks like vs "QN-only". - "Branch protection" — explains the two rulesets (master-mirror-lock and main-qn-pr-review), why direct pushes to master fail, and which CI checks must pass on PRs to main-qn. No content changes elsewhere in the doc — the two-branch model and gh CLI invocations are unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
McSim85
force-pushed
the
qn/fork-contribution-policy
branch
from
8228f9e to
d9545ec
Compare
softalchemy
approved these changes
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This is the policy/process half of the conversation about keeping fork-specific changes from being accidentally contributed upstream. The technical CI fixes in #2 don't belong in
jito-labs/shredstream-proxy, butgh pr createdefaults to upstream and the GitHub web UI's "compare across forks" defaults the base to upstream's master — so there's a real risk someone routes a fork-only change to the wrong place.This PR introduces two lightweight guards that together cost <30 min of setup and catch ~all realistic accidents:
.github/PULL_REQUEST_TEMPLATE.mdGitHub auto-fills the PR body with this when opening any PR. It forces the author to consciously tick one of two boxes:
feature/*branch. Open an upstream PR after this one merges.qn/*branch. Don't open upstream.CONTRIBUTING.mdTop-level doc explaining the convention with concrete examples, the right
gh pr createinvocations for each case (always include--repo!), and a note ongh repo syncfor pulling new upstream commits without ever pushing back.Convention introduced
qn/*feature/*or unprefixedExamples cited:
qn/ci-make-runnable-on-fork(PR Make CI runnable on the QuickNode fork #2) — CI runner switch from Jito's self-hosted pool. Fork-specific.add-listen-port-device-metric-labels(PR Add listen_port and device tags to receiver_stats metric #1, already merged) — new InfluxDB tags onreceiver_stats. Generic. Eligible to upstream.What this does NOT do
GitHub has no native "block contributions to upstream" toggle for forks. This PR is process control, not a hard technical block. If a determined contributor wants to route a
qn/*change upstream, they still can — the template + docs just make it unlikely to happen by accident.If we ever want a hard guard, the next step is the long-lived-vendor-branch model:
mastermirrors upstream exactly,qn-mastercarries our patches, fork's default branch isqn-master. Heavier workflow but stronger separation. Not needed yet.Test plan
🤖 Generated with Claude Code
Note
Low Risk
Low risk: adds only documentation and a GitHub PR template, with no changes to runtime code, build outputs, or CI behavior.
Overview
Adds a new
.github/PULL_REQUEST_TEMPLATE.mdthat prompts authors to explicitly mark whether a change is upstreamable vs QuickNode-specific, with guidance on branch naming and follow-up upstream PRs.Introduces a top-level
CONTRIBUTING.mddocumenting the fork’s two-branch model (main-qnvsmaster), branch protections, and the recommendedghworkflows for landing fork-only changes and cherry-picking upstreamable fixes.Reviewed by Cursor Bugbot for commit d9545ec. Bugbot is set up for automated code reviews on this repo. Configure here.