Skip to content

git-conventions.md

Latest commit

 

History

History
198 lines (138 loc) · 5.69 KB

git-conventions.md

File metadata and controls

198 lines (138 loc) · 5.69 KB

English | Русский

Git Conventions

Conventions for working with Git in the Atomic Spec methodology. Uniformity in naming branches, commits, and PRs ensures the methodology test is met: the project history can be reconstructed from git log.

Branch Naming

Prefix Purpose Example
spec/ Creating or updating an atom (Analyst phase) spec/SPEC-042-cancel-order
feat/ Implementing an atom (Developer phase) feat/SPEC-042-cancel-order
test/ Testing an atom (Tester phase) test/SPEC-042-cancel-order
amend/ Amendment to an existing atom amend/SPEC-042a-extend-window
rfc/ Request for discussion (for BoundaryChange) rfc/SPEC-100-split-orders
domain/ Domain-level changes (multiple atoms) domain/orders-v2
release/ Release preparation release/2025.12

Branch Name Format

<prefix>/<atom-ID>-<short-description>
  • Atom ID — required (except for domain/ and release/)
  • Short description — kebab-case, 2-4 words
  • Latin characters and hyphens only

Commit Message Format

Full Format

<type>(<atom-ID>): <description>

<body>

Change-Type: <change-type>
Gate: <gate>
Breaking: <yes/no>

Example:

spec(SPEC-042): add order cancellation atom

Described Intent, Domain Rules (DR-001, DR-002, DR-003),
Acceptance Criteria (AC-001, AC-002, AC-003).
Constraints: PERF, SEC, IDMP.

Change-Type: FlowChange
Gate: A
Breaking: no

Short Format

For intermediate commits when the context is obvious:

<type>(<atom-ID>): <description>

Examples:

spec(SPEC-042): add negative AC for expired cancellation
feat(SPEC-042): implement cancel-order use case
test(SPEC-042): add test case TC-004 idempotency
amend(SPEC-042a): extend cancellation window to 60 minutes
fix(SPEC-042): fix status check in DR-001

Commit Types

Type Description
spec Change to the spec atom (Analyst sections)
feat Implementation (code + Developer sections)
test Testing (tests + Tester sections)
amend Amendment to an atom
fix Bug fix in specification or code
refactor Refactoring without behavior change
docs Documentation-only changes (not in atoms)
chore Maintenance changes (CI, linters, templates)

PR Conventions

PR Title

[<Gate>] <atom-ID>: <atom title>

Examples:

[Gate A] SPEC-042: Order cancellation by buyer
[Gate B] SPEC-042: Order cancellation by buyer
[Gate C] SPEC-042: Order cancellation by buyer
[Amend]  SPEC-042a: Extend cancellation window

Required Sections in PR Description

The PR description must contain the following sections:

## Atom

- **ID**: SPEC-042
- **Change type**: FlowChange
- **Gate**: Gate A

## What Changed

- Added order cancellation atom
- Described 3 Domain Rules
- Written 3 AC (2 positive, 1 negative)

## Gate Checklist

- [x] A1: Intent is filled in
- [x] A2: Domain Rules exist
- [x] A3: AC are written
- [x] A4: Actors are specified
- [x] A5: Events are specified
- [x] A6: No technical decisions
- [x] A7: Open Questions are closed
- [x] A8: Change type is specified
- [x] A9: Negative AC exist

## Breaking Changes

None

Required Sections

Section Description
Atom ID, change type, gate
What Changed Brief list of changes
Gate Checklist Full checklist of the corresponding gate with marks
Breaking Changes Explicit indication of presence or absence of breaking changes

Rules

1. Atom-first

Spec atom first, then code. You cannot create a PR with code without a corresponding atom that has passed Gate A.

# Correct:
spec/ PR -> merge -> feat/ PR -> merge -> test/ PR -> merge

# Incorrect:
feat/ PR without an existing atom

2. One atom = one PR

Each PR contains changes to only one atom. Exception — domain/ branches, where changes to multiple related atoms are allowed.

3. Change type is required

Every PR that affects an atom must contain Change-Type in the commit description. This is necessary for understanding the scale of changes when reading git log.

Change types: ParameterChange, RuleChange, FlowChange, ModelChange, BoundaryChange, PlatformChange.

For details see Change Types.

4. Breaking Changes require review

If a change is breaking, the PR requires extended review:

  • ModelChange with breaking — review from Architect
  • BoundaryChange — always review from CTO + Architect + Product
  • Change to emits or consumes — review from subscriber owners

Breaking Changes are indicated in the commit:

feat(SPEC-042): change order.cancelled event format

BREAKING CHANGE: field `reason` is now required

Change-Type: ModelChange
Gate: B
Breaking: yes

Related Documents