107 lines
2.7 KiB
Markdown
107 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
1. Fetch upstream: `git fetch origin`
|
|
2. Check for conflicts between your branch and `origin/main`:
|
|
`git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main`
|
|
3. 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.
|