GitFlow and Branching Rules
GitFlow and Branching Rules
Relevant source files
The following files were used as context for generating this wiki page:
This page outlines the mandatory GitFlow procedures for the @primebrick/dal-pg repository. These rules apply to both human contributors and AI agents to ensure codebase stability, consistent versioning, and clean repository history.
Purpose and Scope
The branching strategy is designed to isolate development work, manage releases, and facilitate rapid hotfixing while maintaining a pristine main branch. It strictly enforces the "No v prefix" convention and requires explicit version synchronization within package.json prior to merging.
Branch Naming Conventions
All work must be performed in dedicated branches. Direct commits to develop or main are strictly prohibited docs/gitflow.md:18-18.
| Branch Type | Source Branch | Naming Pattern | Purpose |
|---|---|---|---|
| Feature | develop | feature/<slug> | New functionality or refactoring. Slugs must be lowercase kebab-case docs/gitflow.md:19-19, 105-105. |
| Release | develop | release/<version> | Preparing a new production release. Increments MINOR version docs/gitflow.md:20-20, 82-82. |
| Hotfix | main | hotfix/<version> | Urgent production bug fixes. Increments PATCH version docs/gitflow.md:21-21, 81-81. |
Versioning Rules
- No 'v' Prefix: Do not use
vin branch names (e.g., userelease/0.13.2, notrelease/v0.13.2) docs/gitflow.md:78-78. - Tagging: Git tags must match the version exactly without a prefix (e.g.,
0.13.2) docs/gitflow.md:79-80.
Branch Lifecycle and Data Flow
The following diagram illustrates the flow of code between branches and the synchronization requirements.
GitFlow State Transition
Code
Sources: docs/gitflow.md:16-21, docs/gitflow.md:31-45
Mandatory Closing Procedure
When a task is complete, branches must be closed using a non-fast-forward merge to preserve the group of commits as a single logical unit.
- Merge to Base: Use
git merge --no-ff <branch-name>into the appropriate base branch (developfor features,mainfor release/hotfix) docs/gitflow.md:33-36. - Push Base: Execute
git push origin <base-branch>docs/gitflow.md:38-38. - Local Cleanup: Delete the branch locally using
git branch -d <branch-name>docs/gitflow.md:40-40. - Remote Cleanup: Delete the branch on the origin using
git push origin --delete <branch-name>docs/gitflow.md:42-42. - Alignment: For Release and Hotfix branches,
mainmust be merged back intodevelopto ensuredevelopcontains the latest version bumps and fixes docs/gitflow.md:44-44.
Version Synchronization
The package.json version is the source of truth for CI/CD. The version must be updated and committed on the release/ or hotfix/ branch before merging to main docs/gitflow.md:48-50.
The version-sync.mjs Utility
The repository includes a script scripts/version-sync.mjs that manages this process docs/gitflow.md:66-72.
- It detects the branch type and calculates the expected version from git tags.
- It is triggered automatically via the
prebuildhook duringpnpm run builddocs/gitflow.md:68-68. - Manual Trigger: Use
pnpm run version:autoto sync thepackage.jsonbefore committing docs/gitflow.md:54-54.
Correct Release Sequence
| Step | Command / Action | Purpose |
|---|---|---|
| 1 | git checkout -b release/0.2.0 | Create release branch from develop |
| 2 | pnpm run version:auto | Run version-sync.mjs to update package.json |
| 3 | git add package.json && git commit -m "bump version to 0.2.0" | CRITICAL: Commit version before merge |
| 4 | git checkout main && git merge --no-ff release/0.2.0 | Merge to production |
| 5 | git tag 0.2.0 | Create immutable version tag |
| 6 | git push origin main --tags | Trigger CI for deployment |
Sources: docs/gitflow.md:52-62
Rules for AI Agents
AI agents (e.g., Devin) are subject to additional constraints to prevent unauthorized or accidental modifications.
- Tic-Toc Planning: Agents must generate a plan in
ai-plans/and wait for a "PROCEED" instruction before any code modification .devin/rules/workflow.md:4-15. - Explicit Commit Permission: Agents MUST NEVER commit changes without explicit user instruction (e.g., "procedi con il commit") docs/gitflow.md:7-14.
- Branching: Agents must infer a branch slug and ensure they are on a
feature/branch before the first tracked-file change docs/gitflow.md:101-108.
Common Mistakes to Avoid
- ❌ Committing directly on
developormaindocs/gitflow.md:86-86. - ❌ Forgetting to delete branches (both local and origin) after merge docs/gitflow.md:88-88.
- ❌ Using 'v' prefix in tags or branch names docs/gitflow.md:89-89.
- ❌ Merging to
mainwithout committing thepackage.jsonversion bump first docs/gitflow.md:92-92. - ❌ Creating commits before the feature branch has been created docs/gitflow.md:87-87.
Sources: docs/gitflow.md:84-92