Shift Pull Request Rules

/pr — How Shift pull requests are written

A pull request is one reviewable product or engineering change. Its title must make sense in history and as potential Release Please input.

Title syntax

Every pull request title uses Conventional Commits:

<type>[optional scope][optional !]: <concise imperative description>

Use the same types and subject rules as /commit. Examples:

feat: add source conversion preview
fix(document): preserve the last valid save
ci: publish signed Alpha artifacts

The title must:

• be at most 72 characters;
• use lowercase imperative wording after the colon;
• describe the user or system outcome, not the list of files changed;
• omit trailing punctuation, emoji, agent labels, and [codex] prefixes.

CI rejects titles that are not Conventional Commits. GitHub may also use the pull request title as a squash commit subject, so treat it as release-quality history.

Release Please behavior

Release Please reads conventional commits merged to main and maintains a draft release pull request.

• feat, fix, and perf become public changelog entries.
• refactor, test, docs, build, ci, style, and chore remain valid but are hidden from public release notes.
• Ordinary pull requests must not bump the product version or edit generated changelog sections.
• Maturity and milestone changes require explicit user approval and a Release-As: footer.
• The generated chore: release Shift … pull request is special: review its version, changelog, warning text, and artifact readiness before merging it.

Pull request body

Use a concise body with evidence:

## Summary

- what changed and why
- important behavioral or architectural boundary

## Issue

Closes #123

## Testing

- `exact command`
- focused manual verification

Add ## Risks or ## Follow-up only when they materially help review. Do not add empty sections, generic claims such as “tests pass,” generated marketing prose, or agent attribution.

Testing entries must distinguish:

• commands that passed;
• checks that failed and why;
• checks not run;
• focused manual verification where an automated test would be low value.

For release changes, state whether packaging was smoke-tested and which hosted platform/signing checks remain.

UI review evidence

For materially visible UI changes, attach screenshots or recordings before marking the pull request ready for review.

• Cover every distinct state needed to review the change, including native dialogs and fallback, error, empty, loading, or disabled states when affected.
• Capture the actual implementation. Include before-and-after evidence when the change intentionally modifies existing appearance or interaction.
• Prefer GitHub user attachments over committing review-only media to the repository.
• Redact private user data, credentials, and sensitive documents before uploading.
• If useful evidence cannot be captured safely or reliably, state why in the pull request rather than silently omitting it.

Do not add ceremonial screenshots for changes with no visible review surface.

Desktop E2E impact

For changes that can affect desktop user flows or rendering, complete the E2E impact check in apps/desktop/e2e/README.md before opening or updating the pull request.

• Search existing specs by affected surface, command, or workflow even when the branch does not change E2E files.
• Run the smallest relevant Playwright project, file, and title filter. Run the complete affected project for broad or shared-fixture changes.
• Update visual snapshots only for intentional appearance changes, inspect every changed image, and rerun without update mode.
• List exact E2E commands in ## Testing; explicitly identify relevant E2E coverage not run and why.

Issue linkage

Every ordinary pull request includes ## Issue. Search open and recently closed issues before opening or updating the pull request, and reference every issue materially addressed by the change.

• Use Closes #123 only when the pull request fully satisfies that issue's acceptance criteria. Merging to the default branch then closes the issue.
• Use Refs #123 for partial work, prerequisites, investigation, or related context. The issue remains open.
• If substantial feature, bug, regression, or roadmap work has no adequate issue, invoke /issue and create one before opening the pull request.
• For small maintenance, documentation, dependency, or mechanical work with no issue, write No issue — <brief reason> rather than creating a ceremonial issue.
• Generated Release Please and dependency-bot pull requests are exempt from the issue section.

Never use a closing keyword merely because an issue is related. If any accepted outcome remains, use Refs.