git-commit-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- Vendored from: platform-catalyst/skills/git-commit-practices/SKILL.md (BittahCriminal/platform-catalyst, BSD-3-Clause). Adapted for Catalyst: PLAN.md/CLAUDE.md/DECISIONS.md scrubbed; ADR-008->ADR-001, ADR-009->ADR-002. -->

# Git commit practices

## Role

You guide every contributor (human or AI) to produce commits that satisfy the challenge PDF's "good Git practices" line and the 10% docs/commit-history evaluation criterion. You enforce the safety protocols in `AGENTS.md` (no force-push, no `--no-verify`, no destructive operations without explicit consent) and the Honda Construct principle from the Kaizen log (**`type/kaizen`** Issues + `KAIZEN.md` archive: each commit is one car body on the line — visible, atomic, traceable).

## References

### Research

- *DevOps Unleashed with Git and GitHub* (Packt) — `local/research/devopsunleashedwithgitandgithub.pdf`: branching strategies, commit hygiene, PR workflows, conventional commits, semantic versioning.

### Repo sources of truth

- `AGENTS.md` §"Git Safety Protocol" — never update git config, no force-push to main, no `--no-verify`, no destructive operations without explicit user consent
- `AGENTS.md` §"Committing changes with git" — HEREDOC commit messages, Co-Authored-By trailer for AI assistance
- **`type/kaizen`** GitHub Issues — every merged PR that changed a standard opens (or updates) one Kaizen issue; `KAIZEN.md` is format + archive
- Senior Platform Engineer Project PDF — "good Git practices" + 10% docs eval includes "commit history"

### External

- Conventional Commits 1.0.0: https://www.conventionalcommits.org/
- Git documentation: https://git-scm.com/doc

## Challenge alignment

This skill produces evidence for the **10% Communication & Documentation** rubric ("commit history" as evaluation signal). The PDF explicitly asks to "maintain good Git practices" and notes "iterative value delivery" as a team value — small, frequent, meaningful commits demonstrate that iteration directly.

## Instructions

### 1. Conventional Commits format

Every commit subject line follows:

```
<type>(<scope>): <imperative summary, lowercase, no period>

<optional body — WHY this change, not WHAT>

<optional footer trailers>
```

**Allowed types:**

| Type | When to use |
|------|------------|
| `feat` | New user-facing capability |
| `fix` | Bug correction |
| `refactor` | Code restructure with no behavior change |
| `perf` | Performance improvement |
| `test` | Add or correct tests only |
| `docs` | Documentation only |
| `chore` | Tooling, dependencies, build config |
| `ci` | CI/CD pipeline changes |
| `style` | Whitespace/formatting only (rare; ruff usually handles) |
| `revert` | Revert a previous commit |

**Scopes** (Catalyst conventions): `api`, `lambda`, `infra`, `ci`, `docs`, `cli`, `mcp`, `bedrock`, `state-machine`, `score`, `iam`. Use one per commit when scope is meaningful; omit if the commit truly spans concerns (rare — usually means the commit isn't atomic).

**Examples:**

```
feat(api): add construct-scoped deployments endpoint

Customers need to request deploys without hand-editing Terraform.
This adds POST /v1/.../applications/{app}/deployments which validates
the Score spec, opens a state/pending Issue, and returns the issue
URL for status polling.
```

```
fix(lambda): handle empty SQS batch in webhook-handler

Powertools BatchProcessor returned an empty list when the FIFO queue
drained mid-poll. The handler crashed on the subsequent metric emit.
Guard the metric call and return early.
```

```
refactor(state-machine): extract legal-transitions table to module

Pulled the transition map out of state_machine.py into transitions.py
so the OPA policy can import the same constants. No behavior change.
```

### 2. Atomic single-concern commits

One commit = one logical change. If you can't describe it without "and", split it.

**Bad:**
```
feat(api): add deployments endpoint and fix idempotency bug
```

**Good (two commits):**
```
fix(api): idempotency key collision on concurrent retries
feat(api): add construct-scoped deployments endpoint
```

If you discover unrelated cleanup mid-work, either:
- Commit the cleanup separately *before* your feature work
- Stash, do the cleanup on `main`, rebase

**Never** bundle "while I was in there" changes into a feature commit. Reviewers cannot bisect what they cannot separate.

### 3. Commit message body: WHY, not WHAT

The diff shows WHAT. The body explains WHY. Reviewers and future maintainers need motivation, constraints, alternatives considered.

**Bad body:**
```
This commit adds a new endpoint to the deployments router.
It accepts POST requests and returns 201 on success.
```
(Restates the diff.)

From Cloud-Byte-Consulting/Catalyst, BSD-3-Clause.

More from Cloud-Byte-Consulting/Catalyst