git-workflow-and-versioning

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Workflow and Versioning

## Overview

Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation. With AI agents generating code at high speed, disciplined version control is the mechanism that keeps changes manageable, reviewable, and reversible.

**This repo is a git submodule.** `mezon-bot-ai` is consumed as the `platform/` submodule of the `funix-mezon-bot` superproject (customer pack). All branches, PRs, and merges in this skill happen **inside the submodule** (default branch `main`). Updating the superproject to point at a new submodule commit — the **gitlink bump** — is a separate, manual step that is **never** automated (see "The Submodule Gitlink Bump").

## When to Use

Always. Every code change flows through git.

## Core Principles

### Trunk-Based Development (Recommended)

Keep `main` always deployable. Work in short-lived feature branches that merge back within 1-3 days. Long-lived development branches are hidden costs — they diverge, create merge conflicts, and delay integration. DORA research consistently shows trunk-based development correlates with high-performing engineering teams.

```
main ──●──●──●──●──●──●──●──●──●──  (always deployable — the submodule's default branch)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)
```

This maps onto the OpenSpec change lifecycle, which is **spec-first and two-PR**: one change →
**a `spec/<change>` branch + spec PR** (proposal + delta specs + synced canonical specs; opened by
`/opsx:spec-pr`, merged by a human *before any code*) → then **a `feat/<change>` branch + code PR**
(implementation; opened by `/opsx:ship`, merged by a human). Both PRs live **inside the `platform/`
submodule**. **Never commit on `main`** — branch first; the agent never merges to `main` (a human
merges both PRs). The superproject gitlink bump (`cd <superproject> && git add platform && git commit`)
is a separate manual step.

- **Dev branches are costs.** Every day a branch lives, it accumulates merge risk.
- **Release branches are acceptable.** When you need to stabilize a release while main moves forward.
- **Feature flags > long branches.** Prefer deploying incomplete work behind flags rather than keeping it on a branch for weeks.

### 1. Commit Early, Commit Often

Each successful increment gets its own commit. Don't accumulate large uncommitted changes.

```
Work pattern:
  Implement slice → run toolchain gates → Commit → Next slice

Not this:
  Implement everything → Hope it works → Giant commit
```

Commits are save points. If the next change breaks something, you can revert to the last known-good state instantly. When implementing an OpenSpec change with `/opsx:ship-code`, tick each task in `tasks.md` and commit per work-unit (Red→Green→one commit).

### 2. Atomic Commits

Each commit does one logical thing:

```
# Good: Each commit is self-contained
git log --oneline
a1b2c3d feat(rag-core): add ACL filter to retrieve_kb query
d4e5f6g feat(bot-policy): add refuse_if no_citations to filter stage
h7i8j9k test(rag-core): cover cross-tenant isolation in retrieve_kb
m1n2o3p docs: update retrieve-kb-tool spec for the ACL change

# Bad: Everything mixed together
x1y2z3a add retrieval feature, fix ingestion, bump deps, refactor transport
```

### 3. Descriptive Messages — Conventional Commits

This repo uses **Conventional Commits**. Messages explain the *why*, not just the *what*, and **every commit ends with the Co-Authored-By trailer**:

```
# Good: Explains intent, Conventional Commit type, trailer
feat(rag-core): enforce server-side ACL inside retrieve_kb

Filter KB chunks by the inherited caller identity inside retrieve_kb so
the model can never widen its own access. Keeps the tenant_id-everywhere
and server-side-ACL invariants intact instead of post-filtering results.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

# Bad: Describes what's obvious from the diff, no trailer
update retrieve_kb.py
```

**Format:**
```
<type>(<scope>): <short description>

<optional body explaining why, not what>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
```

**Types:**
- `feat` — New feature
- `fix` — Bug fix
- `refactor` — Code change that neither fixes a bug nor adds a feature
- `test` — Adding or updating tests
- `docs` — Documentation only
- `chore` — Tooling, dependencies, config

Common scopes mirror the repo layout (packages/apps): `rag-core`, `agent-core`,
`ingest-core`, `llm-transport`, `bot-policy`, `backend`, `portal`, `worker-mello`,
`worker-mezon-go`, `kb-mcp`.

### 4. Keep Concerns Separate

Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit — and ideally a separate PR / OpenSpec change:

```
# Good: Separate concerns
git commit -m "refactor(llm-transport): extract MiniMax client helper"
git commit -m "feat(rag-core): pin temperature 0 on synthesize/cite/filter"

# Bad: Mixed concerns
git commit -m "refactor transport and add temperature pinning"
```

**Separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion.

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign