From f0c02c921581c3b09b00fe436ec3ca5b7fa2e351 Mon Sep 17 00:00:00 2001 From: williamhallatt Date: Fri, 6 Mar 2026 13:40:01 +1000 Subject: [PATCH 1/2] docs: add fork contribution workflow to CONTRIBUTING.md (#218) Closes #218 Five gaps identified during PR #217 contribution from a fork: - Fork-first setup instructions in Getting Started - PR process now specifies --base dev and explicit --head - Changeset added as a required step in the PR checklist - Branch Strategy: bradygaster/dev clarified as PR target for all contributions - New 'Keeping Your Fork in Sync' section with rebase instructions Also captures fork procedure in Kobayashi's charter (permanent procedure) and history (lessons from today's session). --- .changeset/docs-fork-contribution-workflow.md | 12 +++++ .squad/agents/kobayashi/charter.md | 23 +++++++++ .squad/agents/kobayashi/history.md | 13 +++++ CONTRIBUTING.md | 50 ++++++++++++++++--- 4 files changed, 91 insertions(+), 7 deletions(-) create mode 100644 .changeset/docs-fork-contribution-workflow.md diff --git a/.changeset/docs-fork-contribution-workflow.md b/.changeset/docs-fork-contribution-workflow.md new file mode 100644 index 000000000..8d2d664ab --- /dev/null +++ b/.changeset/docs-fork-contribution-workflow.md @@ -0,0 +1,12 @@ +--- +"@bradygaster/squad-cli": patch +--- + +docs: add fork contribution workflow to CONTRIBUTING.md + +Closes five gaps discovered during PR #217: +- Fork-first setup instructions (fork → clone → upstream remote) +- PR must target `dev` branch, not `main` (`gh pr create --base dev`) +- Changeset is a required step in the PR process checklist +- `bradygaster/dev` now correctly described as the PR target for all contributions +- New "Keeping Your Fork in Sync" section with rebase-on-upstream/dev instructions diff --git a/.squad/agents/kobayashi/charter.md b/.squad/agents/kobayashi/charter.md index de3fd3bf7..ac65be5ad 100644 --- a/.squad/agents/kobayashi/charter.md +++ b/.squad/agents/kobayashi/charter.md @@ -52,6 +52,29 @@ Squad uses a dev-first, three-branch workflow: - Cross-repo work → separate sibling clones, not worktrees - See `.squad/skills/git-workflow/SKILL.md` for full procedures +### Fork Contributor Procedure + +When contributing to bradygaster/squad from a fork: + +1. **Branch base:** Always create from `upstream/dev`, NOT `upstream/main`: + ```bash + git fetch upstream dev + git checkout -b username/issue-slug upstream/dev + ``` +2. **Changeset:** Run `npx changeset add` and commit the result BEFORE first push. +3. **PR command:** Always specify base and head explicitly: + ```bash + gh pr create --base dev --repo bradygaster/squad --head username:branch-name + ``` +4. **Rebase before PR:** If branch diverged from `upstream/dev`, rebase before opening: + ```bash + git fetch upstream + git rebase --onto upstream/dev {wrong-ancestor-commit} + git push origin branch-name --force-with-lease + ``` + +❌ **Never open a PR targeting `main` from a fork.** `main` is the release branch — it only receives merges from `dev`. + ## Guardrails — Hard Rules **NEVER:** diff --git a/.squad/agents/kobayashi/history.md b/.squad/agents/kobayashi/history.md index e481d71e6..9ae0e2a04 100644 --- a/.squad/agents/kobayashi/history.md +++ b/.squad/agents/kobayashi/history.md @@ -1053,3 +1053,16 @@ Restricts workflow installation in \`squad init\` to only Squad-framework workfl - Version bumps not part of feature PR — revert if accidental, changesets handle release versioning - PR target can be Brady's integration branch (bradygaster/dev) not just main/dev/insiders — confirms Brady's workflow practice - Co-authored-by trailer only required when Copilot actually authors commits (not for human contributors) + +### Fork Contribution Procedure — Lessons from PR #217 (2026-03-06) + +**What went wrong:** +1. PR #217 was opened against `main` instead of `dev`. Had to retarget after creation with `gh pr edit 217 --base dev`. +2. Changeset file was not added before the initial push. Had to add `.changeset/fix-init-noargs-createteam.md` as a separate commit after the fact. +3. Branch was created from `upstream/main` history instead of `upstream/dev`. Required `git rebase --onto upstream/dev {main-ancestor-commit}` to move our 3 commits onto dev's tip. + +**What to do differently:** +- Always create feature branches from `upstream/dev`: `git checkout upstream/dev -b username/issue-slug` +- Always run `npx changeset add` before first push +- PR command for fork contributions: `gh pr create --base dev --repo bradygaster/squad --head username:branch-name` +- If branch is based off wrong ancestor: `git rebase --onto upstream/dev {wrong-ancestor} HEAD` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 983c662ae..21ac56ca8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,9 +35,32 @@ Each package has independent versioning via changesets. A change to squad-sdk ma ### 1. Clone and Install +**Step 1: Fork the repo on GitHub** + +Go to https://github.com/bradygaster/squad and click "Fork" to create your own copy. + +**Step 2: Clone your fork** + ```bash -git clone https://github.com/bradygaster/squad.git +git clone git@github.com:{yourusername}/squad.git cd squad +``` + +**Step 3: Add upstream remote** + +```bash +git remote add upstream git@github.com:bradygaster/squad.git +``` + +**Step 4: Fetch the dev branch** + +```bash +git fetch upstream dev +``` + +**Step 5: Install dependencies** + +```bash npm install ``` @@ -73,6 +96,18 @@ npm run test:watch npm run lint ``` +### 5. Keeping Your Fork in Sync + +Before opening or updating a PR, rebase your branch on the latest upstream dev: + +```bash +git fetch upstream +git rebase upstream/dev +git push origin your-branch --force-with-lease +``` + +Always rebase before opening or updating a PR to ensure your changes are based on the latest integration branch. + ## Development Workflow ### Creating a Feature Branch @@ -114,11 +149,12 @@ The Co-authored-by trailer is **required** for all commits (added by Copilot CLI ### Pull Request Process -1. Push your branch: `git push origin bradygaster/217-readme-help-update` -2. Create a PR: `gh pr create` -3. Link the issue: Add `Closes #217` to PR description -4. Wait for CI checks to pass -5. Request review from the team (agents will respond via comments) +1. Add a changeset: `npx changeset add` (required before PR — see Changesets section) +2. Push your branch: `git push origin {yourusername}/217-readme-help-update` +3. Create a PR with explicit base and head: `gh pr create --base dev --repo bradygaster/squad --head {yourusername}:your-branch` +4. Link the issue: Add `Closes #217` to PR description +5. Wait for CI checks to pass +6. Request review from the team (agents will respond via comments) ## Code Style & Conventions @@ -213,7 +249,7 @@ You don't need to manually version — changesets handle it. - **main** — Stable, published releases. All merges include changesets. - **insider** — Pre-release features, edge cases. Tag releases as `@insider`. -- **bradygaster/dev** — Brady's integration branch (team usage). +- **bradygaster/dev** — Integration branch. **All PRs from forks must target this branch**, not `main`. - **user/issue-slug** — Feature branches from users or agents. ## Continuous Integration From c94731daee143826b85d3b7deb04576eaf99416d Mon Sep 17 00:00:00 2001 From: williamhallatt Date: Fri, 6 Mar 2026 13:49:00 +1000 Subject: [PATCH 2/2] fix(squad): clean session metadata from Kobayashi history MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrote 'Fork Contribution Procedure' entry to contain only reusable procedural knowledge — removed PR numbers, dates, and 'what went wrong' narrative. Kept all actionable commands. --- .squad/agents/kobayashi/history.md | 37 ++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/.squad/agents/kobayashi/history.md b/.squad/agents/kobayashi/history.md index 9ae0e2a04..839a4ae8c 100644 --- a/.squad/agents/kobayashi/history.md +++ b/.squad/agents/kobayashi/history.md @@ -1054,15 +1054,28 @@ Restricts workflow installation in \`squad init\` to only Squad-framework workfl - PR target can be Brady's integration branch (bradygaster/dev) not just main/dev/insiders — confirms Brady's workflow practice - Co-authored-by trailer only required when Copilot actually authors commits (not for human contributors) -### Fork Contribution Procedure — Lessons from PR #217 (2026-03-06) - -**What went wrong:** -1. PR #217 was opened against `main` instead of `dev`. Had to retarget after creation with `gh pr edit 217 --base dev`. -2. Changeset file was not added before the initial push. Had to add `.changeset/fix-init-noargs-createteam.md` as a separate commit after the fact. -3. Branch was created from `upstream/main` history instead of `upstream/dev`. Required `git rebase --onto upstream/dev {main-ancestor-commit}` to move our 3 commits onto dev's tip. - -**What to do differently:** -- Always create feature branches from `upstream/dev`: `git checkout upstream/dev -b username/issue-slug` -- Always run `npx changeset add` before first push -- PR command for fork contributions: `gh pr create --base dev --repo bradygaster/squad --head username:branch-name` -- If branch is based off wrong ancestor: `git rebase --onto upstream/dev {wrong-ancestor} HEAD` +### Fork Contribution Procedure + +Always create feature branches from `upstream/dev`, not `upstream/main`: +```bash +git fetch upstream +git checkout -b username/issue-slug upstream/dev +``` + +Always run `npx changeset add` (or create `.changeset/*.md` manually) before the first push. + +PR command for fork contributions — always specify base and head explicitly: +```bash +gh pr create --base dev --repo bradygaster/squad --head username:branch-name +``` + +If a branch was accidentally created from the wrong ancestor, rebase it onto `upstream/dev`: +```bash +git rebase --onto upstream/dev {wrong-ancestor-commit} HEAD +git push origin branch-name --force-with-lease +``` + +To fix a PR already opened against the wrong base: +```bash +gh pr edit {pr-number} --base dev +```