pr-to-main

PR to Main Branch

Create a PR for a feature/fix branch targeting main in the cc-wf-studio monorepo.

This is a pnpm monorepo with four packages (packages/core, packages/mcp, packages/cli, packages/vscode) and versioning is driven by Changesets, not commit messages. Two monorepo facts shape this workflow:

• A release-worthy change must ship with a .changeset/*.md file in the same PR. Without it, the change merges but never gets released — and pending changesets later block promotion to production.
• Knowing which package(s) changed drives the changeset target, the PR scope, and the commit scope (e.g. fix(vscode):).

So the job here is not just "open a PR" — it's "open a PR that the release pipeline can actually act on."

Workflow

1. Gather context (run in parallel):

   • git status (no -uall)
   • git diff (staged + unstaged) and git diff origin/main...HEAD for the full branch delta
   • git log origin/main..HEAD --oneline for every commit on the branch
   • Check whether the branch tracks a remote and needs pushing
   • ls .changeset/*.md to see whether a changeset already exists

2. Identify scope and type:

   • Affected package(s): map changed paths to packages — packages/core → @cc-wf-studio/core, packages/mcp → @cc-wf-studio/mcp, packages/cli → @cc-wf-studio/cli, packages/vscode → cc-wf-studio (the VSCode extension). Changes outside packages/ (root config, .github/, docs) usually need no release.
   • Type: read the commit prefix, allowing an optional scope — fix: / fix(vscode): → fix, feat: / feat(core): → feat, improvement: → improvement. Review all commits on the branch, not just the latest.

3. Ensure a changeset exists (the monorepo-critical step):

   • If a .changeset/*.md already covers this change, confirm it names the right package(s) and bump level, and move on.
   • If the change should be released and no changeset exists, create one with pnpm changeset — select the affected package(s) from step 2, choose patch/minor/major, and write a one-line summary (this becomes the CHANGELOG entry). Note: bumping @cc-wf-studio/core auto-bumps its dependents, so you don't author separate changesets for cli/mcp.
   • If the change genuinely needs no release (CI-only, tooling, docs), record that intent explicitly with pnpm changeset add --empty so the pipeline isn't left guessing.
   • Why this matters: releases are cut later by manually opening the Release PR (which consumes the accumulated changesets) and merging it — that merge auto-publishes. A PR that lands without the right changeset silently never gets released. (See docs/release-flow.md for the release side — releasing is a human-only action, not something to self-trigger.)

4. Verify the build is green before opening the PR:

   • Run pnpm check && pnpm build from the repo root (Biome + type-checks, then full compilation). Reviewers and CI expect a clean tree, and catching breakage now is cheaper than after review.

5. Select the PR template based on type (from step 2):

   • fix: → assets/fix-template.md
   • feat: → assets/feat-template.md
   • improvement: → assets/improvement-template.md

6. Create the PR:

   • Push the branch with git push -u if it has no upstream.
   • Open it with gh pr create --base main, filling the chosen template.

PR Format

• Language: always write the PR title and body in English (repo rule).
• Title — main merges via squash, so the PR title becomes the squash commit subject. It must therefore follow the commit convention: <type>(<scope>): <description>.
  • <type>: matches the change type from step 2 — fix / feat / improvement / docs / refactor / chore / ci.
  • <scope>: the affected package/area from step 2 — vscode, cli, mcp, core (use the directory name, not the npm name). List several as (cli, mcp). Omit the scope for repo-wide changes (root config, .github/, top-level docs), e.g. ci: guard against pending changesets.
  • <description>: imperative mood, no trailing period, concise (aim ≤50 chars per the commit guideline; GitHub appends a (#NN) suffix, with a leading space, on squash — so don't pad it).
  • Examples (from this repo's history): fix(vscode): parse Changesets-format CHANGELOG, feat(cli): ccwf install-skills subcommand, docs: add root README for the monorepo.
• Body: in the Changes section, write real monorepo paths (packages/vscode/src/..., packages/core/...), not generic placeholders.
• Mention the changeset in the body so reviewers can see the intended release effect — e.g. "Adds a patch changeset for cc-wf-studio" or "No release needed (empty changeset)".

Templates

• fix: assets/fix-template.md — Problem/Solution with Current vs Expected behavior.
• feat: assets/feat-template.md — Summary/Motivation/Changes.
• improvement: assets/improvement-template.md — Before/After comparison.