Ship

Shipping Work

Before You Open a PR

Commit Messages

Conventional Commits Format

<type>(<scope>): <short description>

[optional body explaining WHY]

[optional footer with breaking changes, issue refs]

Common types:

• feat: new feature
• fix: bug fix
• refactor: code restructuring without behavior change
• docs: documentation only
• test: adding/updating tests
• chore: tooling, dependencies, maintenance
• perf: performance improvement
• style: formatting (rarely used -- let formatters do this)

Good vs Bad Messages

Good:

fix: prevent race condition in order submission

Two concurrent submits could both pass the duplicate check
before either was saved. Added row-level lock on order_id.

Fixes #1234

Bad:

update
fix stuff
wip
asdf

Rules

• Subject line under 72 characters
• Imperative mood: "add feature" not "added feature"
• Focus on WHY in the body, WHAT is in the diff
• Reference issues/tickets when relevant
• One logical change per commit

PR Description

## Summary
One sentence: what does this PR do?

## Why
Motivation, context, or ticket link.

## Changes
- Key change 1
- Key change 2
- Breaking changes flagged

## Testing
How was this tested? Screenshots/logs for visible changes.

## Rollout
Any special deploy considerations? Feature flags? Migrations?

## Notes for Reviewer
Trade-offs, open questions, things you're unsure about.

Size Matters

If a PR is growing past 400 lines, split it:

• Separate refactors from feature changes
• Land infrastructure before the feature that uses it
• Ship scaffolding first, fill in later

Release Process

Semantic Versioning

MAJOR.MINOR.PATCH (e.g., 2.4.1)

• MAJOR: breaking changes (incompatible API changes)
• MINOR: new features (backwards compatible)
• PATCH: bug fixes (backwards compatible)

Pre-Release Suffixes

• 1.0.0-alpha.1 -- internal testing
• 1.0.0-beta.1 -- external testing
• 1.0.0-rc.1 -- release candidate

Release Checklist

1. Update CHANGELOG.md with all changes since last release
2. Bump version in package.json / Cargo.toml / pyproject.toml
3. Commit with "chore(release): vX.Y.Z"
4. Tag the commit: git tag -a vX.Y.Z -m "Release vX.Y.Z"
5. Push tag: git push origin vX.Y.Z
6. Create GitHub release with changelog content
7. Publish to package registry (npm, PyPI, crates.io)
8. Announce (Twitter, Slack, blog, etc.)
9. Monitor for issues in first 24-48 hours

CHANGELOG Format

# Changelog

## [2.4.1] - 2026-04-19

### Fixed
- Memory leak in event listener cleanup (#1234)
- Typo in error message

### Changed
- Improved startup time by 40%

## [2.4.0] - 2026-04-01

### Added
- New `/api/v2/search` endpoint
- Support for Redis as cache backend

### Deprecated
- `/api/v1/search` -- use v2 instead, v1 removed in 3.0.0

Deploying

Pre-Deploy Checklist

• All tests pass in CI
• Migrations run cleanly on staging
• Rollback plan documented
• On-call aware
• Feature flags configured (if applicable)
• Monitoring dashboards open

During Deploy

• Watch logs and metrics in real time
• Have rollback one command away
• Don't deploy Friday afternoon (unless fixing a production issue)

After Deploy

• Verify feature works in production (not just "it deployed")
• Check error rates didn't spike
• Check latency didn't regress
• Check that dependent systems still work

Post-Ship

1. Close related issues
2. Update project board/tracker
3. Mention in standup / team channel
4. Write a brief retro if non-trivial: what went well, what would we do differently
5. Follow up on any customer-facing changes (support, docs, marketing)

Anti-Patterns