Skip to content

Development Workflow

Jump to bottom
philipp-gatzka edited this page Dec 24, 2025 · 1 revision

Development Workflow

This document describes the development workflow for the Graphite project.

Overview

Issue → Branch → Commits → Push → PR → Review → Merge → Verify CI

Every change follows this lifecycle. No exceptions.

Branching Strategy

Branch Rules

  • One branch per issue - No exceptions
  • Branch deleted after merge - Automatically by GitHub
  • No direct commits to main - Enforced by branch protection
  • All changes via PR - Required for traceability

Branch Naming

Format: <issue-id>-<issue-title-normalized>

Rules:

  • Lowercase only
  • Spaces become hyphens
  • Remove special characters
  • Max 50 characters

Examples:

  • Issue #42 "Add login button" → 42-add-login-button
  • Issue #7 "Fix API 500 error" → 7-fix-api-500-error

Commit Standards

Message Format

#<issue-id> <message-in-lowercase>

Rules:

  • Must start with # followed by issue number
  • Message must be lowercase
  • Max 72 characters
  • Enforced by commit-msg hook

Examples:

#42 add login button component
#42 add login button styles
#42 add login button tests

Atomic Commits

Non-negotiable: One logical change per commit.

  • One file per commit when possible
  • 30 file changes = 30 commits, not 1 commit
  • Each commit must be self-contained
  • Each commit must be independently understandable

Good example for implementing a user feature:

#42 add user model
#42 add user repository interface
#42 add user repository implementation
#42 add user service
#42 add user controller
#42 add user model tests
#42 add user repository tests
#42 add user service tests
#42 update api documentation

Bad example:

#42 implement user feature  # One commit with 30 files - FORBIDDEN

Pull Request Workflow

Creating a PR

  1. Push your branch to origin
  2. Create PR via GitHub or gh pr create
  3. Fill in the PR template completely

PR Title Format

#<issue-id> <description>

PR Description

Must include:

  • Link to issue: Closes #<id>
  • Summary of changes
  • Testing notes (if applicable)
  • Screenshots (for UI changes)

Merge Requirements

A PR cannot be merged unless:

  • All acceptance criteria checked off
  • Implemented code is covered with automated tests
  • Documentation has been updated
  • At least 1 approval received
  • All CI checks pass
  • No unresolved conversations

Post-Merge

After merging:

  1. Branch is automatically deleted
  2. Verify CI passes on main
  3. If CI fails → Create follow-up issue immediately

Forbidden Actions

  • Direct commits to main
  • Force pushing to main
  • Merging without approval
  • Merging with unchecked acceptance criteria
  • Bulk commits (multiple changes in one commit)
  • Commits without issue reference
  • Leaving failed CI unaddressed

Clone this wiki locally