git

Git Commit and Pull Request Guidelines

Conventional Commits Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

• feat: New features (correlates with MINOR in semantic versioning)
• fix: Bug fixes (correlates with PATCH in semantic versioning)
• docs: Documentation only changes
• refactor: Code changes that neither fix bugs nor add features
• perf: Performance improvements
• test: Adding or modifying tests
• chore: Maintenance tasks, dependency updates, etc.
• style: Code style changes (formatting, missing semicolons, etc.)
• build: Changes to build system or dependencies
• ci: Changes to CI configuration files and scripts

Scope Guidelines

• Scope is OPTIONAL: only add when it provides clarity
• Use lowercase, placed in parentheses after type: feat(transcription):
• Prefer specific component/module names over generic terms
• Your current practice is good: component names (EditRecordingDialog), feature areas (transcription, sound)
• Avoid overly generic scopes like ui or backend unless truly appropriate

When to Use Scope

• When the change is localized to a specific component/module
• When it helps distinguish between similar changes
• When working in a large codebase with distinct areas

When NOT to Use Scope

• When the change affects multiple areas equally
• When the type alone is sufficiently descriptive
• For small, obvious changes

Description Rules

• Start with lowercase immediately after the colon and space
• Use imperative mood ("add" not "added" or "adds")
• No period at the end
• Keep under 50-72 characters on first line

Breaking Changes

• Add ! after type/scope, before colon: feat(api)!: change endpoint structure
• Include BREAKING CHANGE: in the footer with details
• These trigger MAJOR version bumps in semantic versioning

Examples Following Your Style:

• feat(transcription): add model selection for OpenAI providers
• fix(sound): resolve audio import paths in assets module
• refactor(EditRecordingDialog): implement working copy pattern
• docs(README): clarify cost comparison section
• chore: update dependencies to latest versions
• fix!: change default transcription API endpoint

Commit Messages Best Practices

The "Why" is More Important Than the "What"

The commit message subject line describes WHAT changed. The commit body explains WHY.

Good commit (explains motivation):

fix(auth): prevent session timeout during file upload

Users were getting logged out mid-upload on large files because the
session refresh only triggered on navigation, not background activity.

Bad commit (only describes what):

fix(auth): add keepalive call to upload handler

The first commit tells future developers WHY the code exists. The second makes them dig through the code to understand the purpose.

Other Best Practices

• NEVER include Claude Code or opencode watermarks or attribution
• Each commit should represent a single, atomic change
• Write commits for future developers (including yourself)
• If you need more than one line to describe what you did, consider splitting the commit

Pull Request Guidelines

Motivation First

Every PR description MUST start with WHY this change exists. Not what files changed, not how it works—WHY.

Good PR opening:

Users were getting logged out mid-upload on large files. The session refresh only triggered on navigation, not during background activity like uploads.

Bad PR opening:

This PR adds a keepalive call to the upload handler and updates the session refresh logic.

The reader should understand the PROBLEM before they see the SOLUTION.

Code Examples Are Mandatory for API Changes

If the PR introduces or modifies APIs, you MUST include code examples showing how to use them. No exceptions.

What requires code examples:

• New functions, types, or exports
• Changes to function signatures
• New CLI commands or flags
• New HTTP endpoints
• Configuration changes

Good API PR (shows the actual usage):

// Define actions once
const actions = {
	posts: {
		create: defineMutation({
			input: type({ title: 'string' }),
			handler: ({ title }) => client.tables.posts.create({ title }),
		}),
	},
};

// Pass to adapters - they generate CLI commands and HTTP routes
const cli = createCLI(client, { actions });
const server = createServer(client, { actions });

Bad API PR (only describes without showing):

This PR adds an action system that generates CLI commands and HTTP routes from action definitions.

The first version lets reviewers understand the API at a glance. The second forces them to dig through the code to understand the call sites.

Before/After Code Snippets for Refactors

Code examples aren't just for API changes. For internal refactors that change how code is structured without changing the public API, before/after code snippets show reviewers the improvement concretely:

// BEFORE: direct YKeyValueLww usage with manual scanning
const ykv = new YKeyValueLww<unknown>(yarray);

function reconstructRow(rowId) {           // O(n) - scan every cell
  for (const [key, entry] of ykv.map) {
    if (key.startsWith(prefix)) { ... }
  }
}

// AFTER: composed storage layers
const cellStore = createCellStore<unknown>(ydoc, TableKey(tableId));
const rowStore = createRowStore(cellStore);

rowStore.has(id)           // O(1)
rowStore.get(id)           // O(m) where m = fields per row
rowStore.count()           // O(1)

Use before/after snippets when:

• Internal implementation changes significantly even though external API is unchanged
• Performance characteristics change and the code shows why
• Complexity is being moved/decomposed (show what was inlined vs what's now delegated)

Visual Communication with ASCII Art

Use ASCII diagrams liberally to communicate complex ideas. They're more scannable than prose and show relationships at a glance.

Journey/Evolution Diagrams

For PRs that iterate on previous work, show the evolution:

┌─────────────────────────────────────────────────────────────────────────┐
│  PR #1217 (Jan 7)                                                       │
│  "Add YKeyValue for 1935x storage improvement"                          │
│                                                                         │
│       Y.Map (524,985 bytes) ──→ YKeyValue (271 bytes)                   │
│                                                                         │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  PR #1226 (Jan 8)                                                       │
│  "Remove YKeyValue, use native Y.Map + epoch compaction"                │
│                                                                         │
│  Reasoning: "Unpredictable LWW behavior"  ← ⚠️ (misleading!)            │
│                                                                         │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  This PR                                                                │
│  "Restore YKeyValue with LWW timestamps"                                │
│                                                                         │
│  Why: Timestamp-based resolution gives intuitive "latest wins"          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Layered Architecture Diagrams

Show how components stack:

┌─────────────────────────────────────────────────────────────┐
│  defineWorkspace() + workspace.create()                     │  ← High-level
│    Creates Y.Doc internally, binds tables/kv/capabilities   │
├─────────────────────────────────────────────────────────────┤
│  createTables(ydoc, {...}) / createKv(ydoc, {...})          │  ← Mid-level
│    Binds to existing Y.Doc                                  │
├─────────────────────────────────────────────────────────────┤
│  defineTable() / defineKv()                                 │  ← Low-level
│    Pure schema definitions                                  │
└─────────────────────────────────────────────────────────────┘

Comparison Tables

For showing trade-offs between approaches:

┌────────────────────────────────────────────────────────────────┐
│  Use Case                         │  Recommendation            │
├───────────────────────────────────┼────────────────────────────┤
│  Real-time collab, simple cases   │  YKeyValue (positional)    │
│  Offline-first, multi-device      │  YKeyValueLww (timestamp)  │
│  Clock sync unreliable            │  YKeyValue (no clock dep)  │
└────────────────────────────────────────────────────────────────┘

Flow Diagrams

For showing data/control flow:

┌────────────────────────────────────────────────────────────────┐
│                     Conflict Resolution                        │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  Client A (2:00pm)  ──┐                                        │
│                       │──→  Sync  ──→  Winner?                 │
│  Client B (3:00pm)  ──┘                                        │
│                                    │                           │
│                   ┌────────────────┴────────────────┐          │
│                   ▼                                 ▼          │
│             YKeyValue                         YKeyValueLww     │
│          (clientID 

---

*Content truncated.*