Skip to content

docs: improve fork contribution workflow in CONTRIBUTING.md #218

Closed

Description

@williamhallatt

Problem

CONTRIBUTING.md currently assumes contributors have direct push access to the repo. Contributors working from forks encountered several gaps that led to workflow mistakes:

  1. No fork setup instructions — Getting Started shows git clone https://github.com/bradygaster/squad.git but does not explain how to fork first, clone the fork, and add upstream as a remote.

  2. gh pr create has no --base dev flag — The Pull Request Process section says gh pr create with no base specified. This defaults to main, which is wrong. External contributors must target dev explicitly: gh pr create --base dev --repo bradygaster/squad --head username:branch.

  3. Changeset not in the PR checklist — The Changesets section documents how to add a changeset, but the PR Process numbered list doesn't include it as a required step. Easy to skip.

  4. Branch Strategy misleadingly describes bradygaster/dev — Currently says "Brady's integration branch (team usage)" which implies it's internal-only. It should clearly say it's the PR target for all contributions.

  5. No guidance on rebasing before opening a PR — Nothing explains that the fork branch must be rebased on upstream/dev to avoid conflicts before creating the PR.

Proposed Changes

  • Add a "Contributing from a Fork" section covering the full fork workflow
  • Update Pull Request Process to specify --base dev and add changeset as a numbered step
  • Fix Branch Strategy description of bradygaster/dev
  • Add a "Keeping Your Fork in Sync" subsection with rebase instructions

Context

Discovered during PR #217.

Activity

  1. bradygaster commented on Mar 7, 2026

    @bradygaster
    Collaborator

    ✅ Fixed by PR #219 (merged commit 157b8c0) — fork contribution docs added.

    Closed as part of v0.8.21 release wave cleanup.

  2. bradygaster commented on Mar 7, 2026

    @bradygaster
    Collaborator

    Perfect docs improvements, @williamhallatt! Your fork workflow guide (setup, --base dev, changeset checklist, rebase advice) removes key friction points for external contributors. This is exactly the kind of docs update that scales community contributions. Really appreciate it! 📖

    — McManus 📝, on behalf of the Squad

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    release:deferDeferred past next release

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions