Skip to content

Branches, Commits & PRs

Standards for all Liflode / Leoma / Curious Owl repositories. Contractors follow these conventions so tooling, CI, and Linear auto-linking work correctly.

Branch Naming

Format: <type>/<ticket>-<slug>

Type Use
feat New feature or capability
fix Bug fix
chore Dependency update, config change, housekeeping
docs Documentation only
refactor Code restructure without behaviour change
test Tests only
ci CI/CD pipeline changes

Examples:

feat/IT-1234-add-webhook
fix/IT-1235-broken-auth
chore/IT-1236-update-deps
docs/IT-1237-add-runbook
refactor/IT-1238-extract-helpers

Rules:

  • Always include the Linear ticket identifier (e.g. IT-1234)
  • Slug is lowercase kebab-case, max ~40 chars
  • No capital letters, no underscores
  • Branch off main unless told otherwise

Conventional Commits

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

feat(IT-1234): add webhook endpoint for Linear events
fix: handle null response from Linear API
chore(deps): update mkdocs-material to 9.5.4
docs: add restic restore runbook
test(IT-1238): add unit tests for auth helper
ci: enable caching for pip dependencies

Types

Type Use
feat New user-visible feature
fix Bug fix
chore No production logic change (deps, tooling, scripts)
docs Documentation only
refactor Restructure without behaviour change
test Tests only
ci CI/CD pipeline
style Formatting only (whitespace, semicolons)
perf Performance improvement

Scope

Optional. Use the Linear ticket number or a component name — whichever is clearest.

feat(IT-1234): ...      # ticket scope
fix(auth): ...          # component scope
docs: ...               # no scope (fine for small changes)

Body and Footer

Add a body after a blank line for context. Use footers for metadata:

feat(IT-1234): add webhook endpoint for Linear events

Handles push events from GitHub and creates Linear issues via the IT team
queue. Retries up to 3 times on 5xx errors.

Closes IT-1234
  • Closes IT-XXXX — auto-links and closes the Linear issue on merge
  • BREAKING CHANGE: <description> — flags a breaking API or contract change

PR Process

  1. Open as draft immediately after pushing your branch — signals work in progress.
  2. CI must be green before moving out of draft.
  3. Link the Linear issue in the PR description (e.g. Closes IT-1234).
  4. Request review when ready — CODEOWNERS handles auto-assignment.
  5. 1 approval required to merge.
  6. Squash merge only — keeps main history clean. No regular merges, no rebase merges.

PR Template

Each PR uses the org-level template at .github/PULL_REQUEST_TEMPLATE.md. Complete all sections:

  • Summary — what changed and why
  • Linked Linear issue — Closes IT-XXXX or Implements IT-XXXX
  • Test plan — what you tested and how
  • Screenshots — if there are UI changes
  • Breaking changes — Yes or No (if Yes, describe)

CODEOWNERS

Auto-assignment is configured per-repo via .github/CODEOWNERS. If CODEOWNERS is not set for a path, tag @Curious-Owl11 in the PR to route it for review.