Pull Request Guidelines

Creating Pull Requests

Branch Naming

Follow the pattern from Shortcut:

type/sc-[ticket-id]-description

Examples:

• feature/sc-123-add-event-creation
• bugfix/sc-456-fix-login-error

PR Template

Use .github/PULL_REQUEST_TEMPLATE.md for normal pull requests. Keep the sections in this order:

1. Special Release Instructions: Required migrations, data backfills, environment changes, deployment order, monitoring, rollback preparation, compatibility requirements, or required consumer action. Write N/A when the normal release process is sufficient.
2. Purpose: A short plain-language description of what changed. Include a brief reason only when it comes from the ticket or author. Never infer user behavior or business impact. Bullets are fine, but do not repeat details already visible in the diff.
3. Discussions / Callouts: Decisions, tradeoffs, uncertainties, diagrams, or questions that need reviewer attention. Write N/A when there is nothing to discuss.
4. Documentation: Documentation changes or required follow-up. Omit when unused.
5. Testing Instructions: Exact prerequisites and setup. For API changes, include method, URL, authentication or CSRF setup, request payload, expected response, and error cases.
6. QA Evidence: Include evidence from the current change when it helps reviewers reproduce or verify the result. Attach screenshots or link to durable CI artifacts rather than local paths.
7. Related Stories: The primary story plus relevant prerequisites, follow-ups, or stories created as a result of the work when supported by the ticket or author. Omit when no story applies.

Do not add separate Features, Changes, or Additional Notes sections. Release requirements belong at the top; reviewer discussion belongs in Discussions / Callouts.

Migration Labels

Migration labels describe different operational work:

Label	Use for
migration	Schema changes such as creating, altering, renaming, or dropping tables, columns, or indexes
data-migration	Backfills, transforms, or row-level INSERT, UPDATE, DELETE, and data-copy operations

Apply both labels when a PR includes both schema and data operations. A file living in a migrations directory is not enough to choose the label; inspect its contents. Classify raw SQL by its statements: schema-changing SQL uses migration, while SQL that transforms existing rows uses data-migration.

Release PRs use .github/RELEASE_PR_TEMPLATE.md. They list schema and data migrations separately and put their execution and recovery instructions at the top.

Commit Messages

Start all commit messages with the Shortcut story number:

[sc-123] add event creation
[sc-456] resolve date picker issue
[sc-789] update API reference
[sc-101] upgrade dependencies

Code Review

Discord status

Each non-draft PR targeting develop can have one persistent status message in 🛠️・ops-dev. Its title includes the PR number and links back to GitHub. The same message tracks the current head, aggregate applicable CI, the latest effective review decision per reviewer, merge, and applicable server, web app, or marketing development deployments. Review states are approved, changes requested, or commented.

Drafts don't create a message, but marking a draft ready for review can. Ordinary PR conversation comments and standalone inline-comment events don't trigger Discord updates. A submitted review with inline comments appears as a commented review, but thread counts aren't shown. Depending on repository settings, the reviewers role can be mentioned when the message is first created and once for a new CI or deployment failure. See the CI/CD pipeline guide for the notification switches and failure-alert behavior.

Trusted same-repository PRs targeting qa or main use a separate persistent card in the matching operations channel. That card follows CI and reviews before merge, then release publication, deployments, and artifact links. New failures produce a separate operations role alert with a direct link to the failed Actions run. See QA and production status for association, fallback, artifact, and alert behavior.

Before Requesting Review

• [ ] Code builds without errors
• [ ] Linting passes (pnpm run lint)
• [ ] Self-review your changes
• [ ] Update relevant documentation

Merge Process

1. Create PR from feature branch to develop
2. Request review from teammate
3. Address any feedback
4. Merge when approved

Deployment Flow

feature/* → develop → qa → main
              ↓        ↓      ↓
           Dev Env  QA Env  Production

All deployments happen automatically via GitHub Actions when branches are updated.