Git Workflow Rules

Commit Message Format

type(scope): imperative summary

Problem: describe the issue or motivation

Solution: describe what this commit does

Header

type (required): feat fix docs refactor perf test ci build revert
scope (optional): lowercase module/area name, e.g. feat(parser):
summary: imperative mood, lowercase after colon, no trailing period, max 72 chars

Body

Required for any non-trivial change. Use Problem: / Solution: sections. 2-3 sentences per section, max. Wrap at 72 characters. Separate from header with a blank line.

Use backticks around code identifiers, function names, and file paths (e.g. setup(), lua/oil/view.lua, FIELD_NAME).

Examples

Good:

fix(lsp): correct off-by-one in `diagnostic_range`

Problem: diagnostics highlighted one character past the actual error,
causing confusion on adjacent tokens.

Solution: subtract 1 from the end column returned by the language
server before converting to 0-indexed nvim columns.

refactor: extract repeated buffer lookup into `get_buf_entry`

Bad:

Fixed stuff
feat: Add Feature.
fix(lsp): correct off-by-one in diagnostic range and also refactor the
entire highlight module and add new tests

Branch Rules

Always work on a feature branch. Never commit or push directly to main or master. If on the default branch, create and switch to a topic branch first.

type/short-description

Examples: fix/diagnostic-range, feat/code-actions, refactor/highlight-module

PR Body Format

If the repo has .github/pull_request_template.md, follow that template exactly.

If no template exists, fall back to:

## Problem

<1-2 sentences>

## Solution

<1-2 sentences>

Write concise prose. No bullet-point walls, no verbose AI-style markdown. Use backticks for code references.

Post-PR Steps

After creating a PR, immediately:

Fetch upstream: git fetch origin
Check for conflicts between your branch and origin/main: git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main
If conflicts exist, rebase or merge origin/main into the branch and resolve them before considering the PR done.

GPG Signing

If GPG signing fails for any reason, retry the commit or push with --no-gpg-sign rather than stopping.

Decomposition Rules

One logical change per commit.
Refactors go in their own commit before the feature that depends on them.
Formatting/style changes are never mixed with behavioral changes.
Test-only commits are fine when adding coverage for existing code.
If a PR has more than ~3 commits, consider whether it should be split into separate PRs.

2.7 KiB Raw Blame History