git-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Practices

These are the conventions for all git operations in this project. Every branch, commit, and pull request follows these rules without exception.

## Branch Naming

**Format:** `<type>/<ticket-id>`

**Types:**
- `feat` — New feature or capability
- `fix` — Bug fix
- `refactor` — Code restructuring without behavior change
- `chore` — Maintenance, tooling, config, dependencies

**Examples:**
```
feat/CTR-12
fix/CTR-45
refactor/CTR-78
chore/CTR-99
```

**Rules:**
- Ticket ID matches the project tracker (JIRA, Linear, etc.)
- Lowercase everything
- No descriptions in branch name — the ticket ID is the reference
- One branch per ticket — don't combine work from multiple tickets

## Commit Messages

**Format:**
```
<type>(<scope>): <short message> [<ticket-id>]

<description>
```

**Line 1 (subject):**
- `type` — Same as branch types, plus: `docs` (documentation), `test` (tests only)
- `scope` — One word indicating the module or layer affected (e.g., `auth`, `api`, `database`, `ui`, `config`)
- `short message` — Imperative mood, lowercase, no period, under 50 characters after the scope
- `ticket-id` — In square brackets at the end

**Line 2:** Blank line (always)

**Line 3+ (description):**
- What was done and why, in plain sentences
- Reference related files or decisions if helpful
- Keep it concise — enough context for someone reading git log, not a full essay

**Examples:**
```
feat(document): implement search by text [CTR-12]

Added full-text search to the document module using the existing
search index. Follows the pattern established in the user search
feature.
```

```
fix(auth): prevent token refresh race condition [CTR-45]

Two concurrent requests could both trigger a token refresh,
causing one to fail with an invalid token error. Added a mutex
to ensure only one refresh happens at a time.
```

```
refactor(api): extract validation middleware [CTR-78]

Moved request validation logic from individual route handlers
into a shared middleware. Reduces duplication across 12 endpoints.
```

```
chore(config): update dependencies to latest stable [CTR-99]

Bumped all non-major dependencies. No breaking changes detected.
```

```
test(billing): add edge cases for prorated charges [CTR-33]

Covers: mid-cycle upgrade, downgrade on last day, zero-usage
month, and negative balance scenarios.
```

```
docs(api): update endpoint documentation for v2 routes [CTR-55]

Reflects the new response format introduced in the API v2 migration.
```

**Rules:**
- Subject line is mandatory, description is mandatory for anything beyond trivial changes
- No co-author or AI attribution lines
- One logical change per commit — if you have to use "and" in the subject, consider splitting
- The type in the commit matches the branch type (a `feat/` branch should have `feat()` commits, with occasional `test()` or `docs()` commits for supporting work)

## Pull Requests

**Title format:** Same as commit subject line:
```
<type>(<scope>): <short message> [<ticket-id>]
```

**Body format:**
```markdown
## Summary
[2-4 sentences: what this PR does and why. Written for a reviewer
who hasn't read the ticket — they should understand the change
from this summary alone.]

## Changes
- [Concrete change 1 — what file/module and what was done]
- [Concrete change 2]
- [Concrete change 3]

## Testing

From ovargas/virtual-team, MIT.

More from ovargas/virtual-team