PR Workflow

Because The Shift Platform uses git submodules, where you open a pull request depends on what you changed. This page explains the workflow.

Where PRs Go

Change in	PR goes to
A submodule (e.g., yellowpages/, passport/)	The submodule's own repository
Gateway (packages/gateway/)	Platform repository
Platform Core (packages/core/)	Platform repository
Convex schema/functions (convex/)	Platform repository
Scripts (scripts/)	Platform repository
Root config (package.json, tsconfig.json, etc.)	Platform repository
Submodule pointer update	Platform repository (after submodule PR merges)

Submodule Change Workflow

When your change is in a submodule:

1. Work inside the submodule

cd yellowpages
git checkout -b feature/my-change
# Make changes
git add .
git commit -m "feat: add new endpoint"
git push origin feature/my-change

2. Open a PR in the submodule repo

Open the PR in the submodule's repository (e.g., the-shift-dev/yellowpages). Get it reviewed and merged.

3. Update the platform pointer

After the submodule PR merges, update the platform to reference the new commit:

cd ..  # back to platform root
cd yellowpages
git checkout main
git pull
cd ..
git add yellowpages
git commit -m "Update yellowpages submodule"
git push

This can be a direct push or a separate PR to the platform repo, depending on your team's convention.

Platform Change Workflow

When your change is in the gateway, core library, or root configuration:

# From the platform root
git checkout -b feature/my-change
# Make changes in packages/gateway, packages/core, convex/, etc.
git add .
git commit -m "feat: add new gateway middleware"
git push origin feature/my-change

Then open a PR in the platform repository.

Mixed Changes

If your change spans both a submodule and the platform (e.g., adding a new export to @shift/platform-core and consuming it in a service):

1. Make the platform-core change first and merge it
2. Update the submodule's dependency, commit, push, and merge the submodule PR
3. Update the platform's submodule pointer

Alternatively, you can develop both changes locally using symlinks (Bun resolves workspace symlinks), then split them into separate PRs when ready.

Before Submitting

Regardless of where the PR goes, always run:

# From the platform root
bun run check    # Biome lint + format
bun run test     # All tests

If you changed Convex schema or functions:

npx convex deploy --dry-run  # Verify schema changes

CI Checks

The CI pipeline runs on every PR:

1. Lint -- bun run check
2. Test -- bun run test
3. Build -- Docker image build (ensures nothing is broken)

All checks must pass before merging.

Commit Messages

Follow conventional commit format:

feat: add new endpoint for bulk operations
fix: handle empty response from Convex
docs: update API reference for palette service
refactor: extract store factory pattern
test: add integration tests for ledger policies

When using Claude Code, commits include the co-author trailer:

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>